fix: improve session recovery guidance

Author: thymikee

src/daemon-client.ts

@@ -1765,11 +1765,23 @@ export function resolveDaemonStartupHint(
     process.env.AGENT_DEVICE_STATE_DIR,
   ),
 ): string {
+  const cleanupCommand = buildDaemonMetadataCleanupCommand(paths);
   if (state.hasLock && !state.hasInfo) {
-    return `agent-device attempted to clean stale daemon metadata automatically, but ${paths.lockPath} still exists without ${paths.infoPath}. Retry with --debug; if this persists, remove ${paths.lockPath} after confirming no agent-device daemon process is running.`;
+    return `agent-device attempted to clean stale daemon metadata automatically, but ${paths.lockPath} still exists without ${paths.infoPath}. Retry with --debug; if this persists after confirming no agent-device daemon process is running, run: ${cleanupCommand}`;
   }
   if (state.hasLock && state.hasInfo) {
-    return `agent-device attempted to clean stale daemon metadata automatically, but ${paths.infoPath} and ${paths.lockPath} still remain. Retry with --debug; if this persists, remove both files after confirming no agent-device daemon process is running.`;
+    return `agent-device attempted to clean stale daemon metadata automatically, but ${paths.infoPath} and ${paths.lockPath} still remain. Retry with --debug; if this persists after confirming no agent-device daemon process is running, run: ${cleanupCommand}`;
   }
-  return `agent-device did not observe reachable daemon metadata after retrying. Stale metadata was cleaned automatically when safe; retry with --debug and check daemon diagnostics logs.`;
+  if (state.hasInfo) {
+    return `agent-device did not observe reachable daemon metadata after retrying, and ${paths.infoPath} still remains. Stale metadata was cleaned automatically when safe; retry with --debug. If this persists after confirming no agent-device daemon process is running, run: ${cleanupCommand}`;
+  }
+  return `agent-device did not observe reachable daemon metadata after retrying. Stale metadata was cleaned automatically when safe; retry with --debug and check daemon diagnostics logs. If stale metadata returns after confirming no agent-device daemon process is running, run: ${cleanupCommand}`;
+}
+
+function buildDaemonMetadataCleanupCommand(paths: Pick<DaemonPaths, 'infoPath' | 'lockPath'>) {
+  return `rm -f ${shellQuote(paths.infoPath)} ${shellQuote(paths.lockPath)}`;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
 }

src/daemon/__tests__/request-execution-scope.test.ts

@@ -88,7 +88,7 @@ test('prepareLockedRequestScope preserves existing-session selector validation',
       sessionStore,
       trackDownloadableArtifact: () => 'artifact-id',
     }),
-  ).toThrow(/cannot be used with --platform=ios/i);
+  ).toThrow(/already bound to android device "Pixel" \(emulator-5554\).*--platform=ios/i);
 });
 
 test('prepareLockedRequestScope blocks commands for invalidated recordings before handlers run', async () => {

src/daemon/__tests__/request-finalization.test.ts

@@ -0,0 +1,31 @@
+import { test, expect } from 'vitest';
+import { finalizeDaemonResponse } from '../request-finalization.ts';
+import type { DaemonRequest, DaemonResponse } from '../types.ts';
+
+test('finalizeDaemonResponse preserves handler error hints from details', () => {
+  const req: DaemonRequest = {
+    token: 'token',
+    session: 'default',
+    command: 'open',
+    positionals: [],
+    flags: {},
+  };
+  const response: DaemonResponse = {
+    ok: false,
+    error: {
+      code: 'DEVICE_IN_USE',
+      message: 'Device is already in use by session "default".',
+      details: {
+        session: 'default',
+        hint: 'Run agent-device session list and reuse --session default.',
+      },
+    },
+  };
+
+  const finalized = finalizeDaemonResponse(req, response, () => 'artifact-id');
+
+  expect(finalized.ok).toBe(false);
+  if (!finalized.ok) {
+    expect(finalized.error.hint).toBe('Run agent-device session list and reuse --session default.');
+  }
+});

src/daemon/__tests__/request-lock-policy.test.ts

@@ -2,6 +2,7 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { applyRequestLockPolicy } from '../request-lock-policy.ts';
 import type { SessionState } from '../types.ts';
+import { AppError } from '../../utils/errors.ts';
 
 const IOS_SESSION: SessionState = {
   name: 'qa-ios',
@@ -32,6 +33,21 @@ const ANDROID_SESSION: SessionState = {
   },
 };
 
+const RECORDING_SESSION: SessionState = {
+  ...ANDROID_SESSION,
+  name: 'default',
+  recordingSession: true,
+  recording: {
+    platform: 'android',
+    outPath: '/tmp/recording.mp4',
+    remotePath: '/sdcard/recording.mp4',
+    remotePid: '1234',
+    startedAt: Date.now(),
+    showTouches: false,
+    gestureEvents: [],
+  },
+};
+
 test('rejects fresh-session selector conflicts under request lock policy', () => {
   assert.throws(
     () =>
@@ -52,6 +68,37 @@ test('rejects fresh-session selector conflicts under request lock policy', () =>
   );
 });
 
+test('reject lock policy explains fresh-session recovery commands', () => {
+  assert.throws(
+    () =>
+      applyRequestLockPolicy({
+        token: 'token',
+        session: 'qa-ios',
+        command: 'snapshot',
+        positionals: [],
+        flags: {
+          device: 'Pixel 9',
+        },
+        meta: {
+          lockPolicy: 'reject',
+          lockPlatform: 'ios',
+        },
+      }),
+    (error) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /snapshot is using a bound-session lock for ios/i);
+      assert.match(error.message, /--device=Pixel 9/i);
+      assert.match(error.details?.hint ?? '', /Remove conflicting device selectors/i);
+      assert.match(
+        error.details?.hint ?? '',
+        /agent-device open <app> --session qa-ios --platform ios/i,
+      );
+      assert.match(error.details?.hint ?? '', /agent-device session list/i);
+      return true;
+    },
+  );
+});
+
 test('allows open to choose a fresh-session target under request lock policy', () => {
   const req = applyRequestLockPolicy({
     token: 'token',
@@ -118,6 +165,66 @@ test('rejects existing-session selector conflicts under request lock policy', ()
   );
 });
 
+test('reject lock policy explains existing-session recovery commands', () => {
+  assert.throws(
+    () =>
+      applyRequestLockPolicy(
+        {
+          token: 'token',
+          session: 'qa-ios',
+          command: 'snapshot',
+          positionals: [],
+          flags: {
+            serial: 'emulator-5554',
+          },
+          meta: {
+            lockPolicy: 'reject',
+          },
+        },
+        IOS_SESSION,
+      ),
+    (error) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /locked to session "qa-ios"/i);
+      assert.match(error.message, /ios device "iPhone 16" \(SIM-001\)/i);
+      assert.match(error.message, /--serial=emulator-5554/i);
+      assert.match(error.details?.hint ?? '', /agent-device session list/i);
+      assert.match(error.details?.hint ?? '', /--session qa-ios/i);
+      assert.match(error.details?.hint ?? '', /agent-device close --session qa-ios/i);
+      return true;
+    },
+  );
+});
+
+test('reject lock policy explains recording-session recovery commands', () => {
+  assert.throws(
+    () =>
+      applyRequestLockPolicy(
+        {
+          token: 'token',
+          session: 'default',
+          command: 'snapshot',
+          positionals: [],
+          flags: {
+            device: 'Pixel 8',
+          },
+          meta: {
+            lockPolicy: 'reject',
+          },
+        },
+        RECORDING_SESSION,
+      ),
+    (error) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /locked to session "default"/i);
+      assert.match(error.details?.hint ?? '', /recording session "default"/i);
+      assert.match(error.details?.hint ?? '', /agent-device record stop --session default/i);
+      assert.match(error.details?.hint ?? '', /agent-device close --session default/i);
+      return true;
+    },
+  );
+});
+
 test('allows inventory commands to use explicit Apple selectors under another lock platform', () => {
   const req = applyRequestLockPolicy({
     token: 'token',

src/daemon/__tests__/request-router-lock-policy.test.ts

@@ -67,6 +67,8 @@ test('direct daemon requests cannot bypass reject lock policy for existing sessi
   if (!response.ok) {
     expect(response.error.code).toBe('INVALID_ARGS');
     expect(response.error.message).toMatch(/--udid=SIM-999/i);
+    expect(response.error.hint).toMatch(/agent-device session list/i);
+    expect(response.error.hint).toMatch(/agent-device close --session qa-ios/i);
   }
 });
 
@@ -108,6 +110,8 @@ test('batch steps cannot bypass reject lock policy on nested direct requests', a
     expect(response.error.code).toBe('INVALID_ARGS');
     expect(response.error.message).toMatch(/Batch failed at step 1/i);
     expect(response.error.message).toMatch(/--serial=emulator-5554/i);
+    expect(response.error.hint).toMatch(/agent-device session list/i);
+    expect(response.error.hint).toMatch(/agent-device close --session qa-ios/i);
   }
 });
 

src/daemon/__tests__/session-selector.test.ts

@@ -43,6 +43,23 @@ test('rejects mismatched platform selector', () => {
   );
 });
 
+test('selector mismatch explains session recovery commands', () => {
+  const session = makeSession();
+  assert.throws(
+    () => assertSessionSelectorMatches(session, { platform: 'ios' }),
+    (err: unknown) => {
+      assert.ok(err instanceof AppError);
+      assert.equal(err.code, 'INVALID_ARGS');
+      assert.match(err.message, /Session "default" is already bound to android device "Pixel 9"/i);
+      assert.match(err.message, /--platform=ios/i);
+      assert.match(err.details?.hint ?? '', /agent-device session list/i);
+      assert.match(err.details?.hint ?? '', /--session default/i);
+      assert.match(err.details?.hint ?? '', /agent-device close --session default/i);
+      return true;
+    },
+  );
+});
+
 test('accepts --platform apple alias for ios sessions', () => {
   const session = makeSession({
     device: {

src/daemon/handlers/__tests__/record-trace.test.ts

@@ -226,6 +226,94 @@ test('record stop derives telemetry artifact local path from client outPath', as
   expect((responseStop as any).data?.telemetryPath).toBe(deriveRecordingTelemetryPath(finalOut));
 });
 
+test('record stop releases session created only for recording', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'record-only-session';
+  const session = makeSession(sessionName, {
+    platform: 'ios',
+    id: 'ios-sim-1',
+    name: 'iPhone 16',
+    kind: 'simulator',
+    booted: true,
+  });
+  session.recordingSession = true;
+  session.recording = {
+    platform: 'ios',
+    child: { kill: vi.fn(), pid: 123 },
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+    outPath: path.join(os.tmpdir(), 'record-only.mp4'),
+    startedAt: Date.now(),
+    showTouches: false,
+    gestureEvents: [],
+  };
+  sessionStore.set(sessionName, session);
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)).toBeUndefined();
+});
+
+test('record stop releases record-only session even when recording state is stale', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'stale-record-only-session';
+  const session = makeSession(sessionName, {
+    platform: 'ios',
+    id: 'ios-sim-1',
+    name: 'iPhone 16',
+    kind: 'simulator',
+    booted: true,
+  });
+  session.recordingSession = true;
+  sessionStore.set(sessionName, session);
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(response?.ok).toBe(false);
+  expect(sessionStore.get(sessionName)).toBeUndefined();
+});
+
+test('record stop keeps normal app session open after recording', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'app-session';
+  const session = makeSession(sessionName, {
+    platform: 'ios',
+    id: 'ios-sim-1',
+    name: 'iPhone 16',
+    kind: 'simulator',
+    booted: true,
+  });
+  session.appBundleId = 'com.apple.Preferences';
+  session.recording = {
+    platform: 'ios',
+    child: { kill: vi.fn(), pid: 123 },
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+    outPath: path.join(os.tmpdir(), 'app-session.mp4'),
+    startedAt: Date.now(),
+    showTouches: false,
+    gestureEvents: [],
+  };
+  sessionStore.set(sessionName, session);
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(sessionStore.get(sessionName)).toBe(session);
+  expect(sessionStore.get(sessionName)?.recording).toBeUndefined();
+});
+
 test('record start resolves relative output path from request cwd', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-cwd';