tell direct-remote users to redeploy when a stack backup can't find its files

tests/backups/backup-script.test.ts

@@ -160,17 +160,33 @@ describe('buildBackupScript', () => {
 			expect(script).toContain('compose dupa.yaml not found');
 		});
 
-		it('user-set hint: same clear "set the real host path" instruction', () => {
+		it('user-set hint (hawser): same clear "set the real host path" instruction', () => {
 			const script = buildBackupScript(['backup', '/volumes/', '/metadata/'], {
 				volumeKey: '__dockhand_stackdir__', composeFileName: 'compose.yaml',
 				hostPath: '/opt/agent/stacks/gitlab',
-				hint: { kind: 'user-set', hostPath: '/opt/agent/stacks/gitlab', envName: 'remote-1' }
+				hint: { kind: 'user-set', transport: 'hawser', hostPath: '/opt/agent/stacks/gitlab', envName: 'remote-1' }
 			});
 			expect(script).toContain('not found in /opt/agent/stacks/gitlab on remote-1');
 			expect(script).toContain('Set "Remote stack path (for backup)" in Settings > Environments > remote-1');
 			expect(script).not.toContain('Redeploy the stack');
 		});
 
+		it('user-set hint (direct-remote): the path is set, so tell them to REDEPLOY (files are staged on up), not to change the path', () => {
+			const script = buildBackupScript(['backup', '/volumes/', '/metadata/'], {
+				volumeKey: '__dockhand_stackdir__', composeFileName: 'compose.yaml',
+				hostPath: '/home/ubuntu/Docker/dockhand/cf-tunnel',
+				hint: { kind: 'user-set', transport: 'direct', hostPath: '/home/ubuntu/Docker/dockhand/cf-tunnel', envName: 'DOOBER' }
+			});
+			// Apostrophes in the message are shell-escaped in the generated script, so match on
+			// apostrophe-free fragments here; the exact wording is asserted in stackdir-plan.test.ts
+			// against the pure builder.
+			expect(script).toContain('not found in /home/ubuntu/Docker/dockhand/cf-tunnel on DOOBER');
+			expect(script).toContain('The Remote stack path is set');
+			expect(script).toContain('redeploy the stack so Dockhand stages them');
+			// It must NOT tell them to set the path (they already did) - that was the confusing advice.
+			expect(script).not.toContain('Set "Remote stack path (for backup)"');
+		});
+
 		it('falls back to "on the host" when the env name is unknown (never prints null)', () => {
 			const script = buildBackupScript(['backup', '/volumes/', '/metadata/'], {
 				volumeKey: '__dockhand_stackdir__', composeFileName: 'compose.yaml',
@@ -221,7 +237,8 @@ describe('buildBackupScript', () => {
 		// generated script through sh for each hint kind to guarantee it stays valid.
 		for (const hint of [
 			{ kind: 'hawser-defaulted', hostPath: '/data/stacks/x', envName: "prod's-env (eu)" } as const,
-			{ kind: 'user-set', hostPath: '/opt/agent/stacks/x', envName: 'remote-1' } as const,
+			{ kind: 'user-set', transport: 'hawser', hostPath: '/opt/agent/stacks/x', envName: 'remote-1' } as const,
+			{ kind: 'user-set', transport: 'direct', hostPath: '/opt/agent/stacks/x', envName: "prod's-env (eu)" } as const,
 			{ kind: 'local' } as const,
 		]) {
 			it(`round-trip: generated probe script is valid sh for hint kind=${hint.kind}`, () => {

tests/backups/stackdir-plan.test.ts

@@ -17,6 +17,7 @@ import {
 	STACKDIR_VOLUME_KEY,
 	isReservedVolumeKey,
 	stackDirSource,
+	stackDirProbeFixHint,
 	type HostStackDirInput,
 } from '../../src/lib/server/backups/stackdir-plan';
 
@@ -316,3 +317,57 @@ describe('tagCapturedEntries — mark stack-dir entries that are also a bind', (
 		expect(out[0].capturedAs).toBeUndefined();
 	});
 });
+
+describe('stackDirProbeFixHint', () => {
+	test('direct-remote user-set: tells the user to REDEPLOY (path is set, files staged on up), never to change the path', () => {
+		const msg = stackDirProbeFixHint(
+			{ kind: 'user-set', transport: 'direct', hostPath: '/home/ubuntu/Docker/dockhand/cf-tunnel', envName: 'DOOBER' },
+			'/home/ubuntu/Docker/dockhand/cf-tunnel',
+		);
+		expect(msg).toContain("The Remote stack path is set, but this stack's files aren't on DOOBER yet");
+		expect(msg).toContain('redeploy the stack so Dockhand stages them at /home/ubuntu/Docker/dockhand/cf-tunnel');
+		expect(msg).toContain("down/start/restart don't copy; it must be a deploy");
+		// The confusing advice must be gone - the user already set the path.
+		expect(msg).not.toContain('Set "Remote stack path (for backup)"');
+	});
+
+	test('hawser user-set: keeps the "set the real host path" advice (agent keeps files under its own dir)', () => {
+		const msg = stackDirProbeFixHint(
+			{ kind: 'user-set', transport: 'hawser', hostPath: '/opt/agent/stacks/gitlab', envName: 'remote-1' },
+			'/opt/agent/stacks/gitlab',
+		);
+		expect(msg).toContain('Set "Remote stack path (for backup)" in Settings > Environments > remote-1');
+		expect(msg).not.toContain('redeploy');
+	});
+
+	test('hawser-defaulted: set the real host path', () => {
+		const msg = stackDirProbeFixHint(
+			{ kind: 'hawser-defaulted', hostPath: '/data/stacks/x', envName: 'prod' },
+			'/data/stacks/x',
+		);
+		expect(msg).toContain('Set "Remote stack path (for backup)" in Settings > Environments > prod');
+	});
+
+	test('no env name: falls back to plain "Settings > Environments" (never prints null)', () => {
+		const msg = stackDirProbeFixHint(
+			{ kind: 'hawser-defaulted', hostPath: '/data/stacks/x', envName: null },
+			'/data/stacks/x',
+		);
+		expect(msg).toContain('Settings > Environments to the real host path');
+		expect(msg).not.toContain('null');
+	});
+
+	test('direct-remote user-set with no env name: still says redeploy, no null', () => {
+		const msg = stackDirProbeFixHint(
+			{ kind: 'user-set', transport: 'direct', hostPath: '/x', envName: null },
+			'/x',
+		);
+		expect(msg).toContain("this stack's files aren't on the host yet");
+		expect(msg).toContain('redeploy the stack');
+		expect(msg).not.toContain('null');
+	});
+
+	test('local: redeploy stages the files', () => {
+		expect(stackDirProbeFixHint({ kind: 'local' }, '/srv/stacks/app')).toContain('Redeploy the stack to stage its files there');
+	});
+});