fix: improve session ownership and recovery guidance (#674)

* fix: improve session recovery guidance

* fix: quote session recovery commands

* test: simplify record session cleanup fixtures

* test: cover recovery hint edge cases

* test: trim duplicate recovery quoting coverage

* fix: scope implicit sessions by caller workspace

* fix: surface session state directory

* fix: remove unused session store check

* test: trim duplicate session recovery coverage

Author: thymikee

skills/dogfood/SKILL.md

@@ -22,6 +22,6 @@ Read current CLI guidance:
 agent-device help dogfood
 ```
 
-Loop: open named session -> snapshot -i + screenshot -> explore flows -> capture evidence per issue -> close.
+Loop: open app -> snapshot -i + screenshot -> explore flows -> capture evidence per issue -> close.
 
 Target app is required; infer platform or ask. Findings must come from runtime behavior, not source reads. Let `help dogfood` provide exact report shape, evidence commands, and current workflow guidance.

src/cli.ts

@@ -215,7 +215,7 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
           currentFlags: CliFlags,
           runtime: SessionRuntimeHints | undefined,
         ): AgentDeviceClientConfig => ({
-          session: currentFlags.session ?? sessionName,
+          session: currentFlags.session,
           requestId,
           stateDir: currentFlags.stateDir,
           daemonBaseUrl: currentFlags.daemonBaseUrl,

src/client-normalizers.ts

@@ -333,6 +333,7 @@ export function buildMeta(options: InternalRequestOptions): DaemonRequest['meta'
   return stripUndefined({
     requestId: options.requestId,
     cwd: options.cwd,
+    sessionExplicit: options.session !== undefined,
     debug: options.debug,
     lockPolicy: options.lockPolicy,
     lockPlatform: options.lockPlatform,

src/client-shared.ts

@@ -140,6 +140,7 @@ export function serializeOpenResult(result: AppOpenResult): Record<string, unkno
   return withSuccessText(
     {
       session: result.session,
+      ...(result.sessionStateDir ? { sessionStateDir: result.sessionStateDir } : {}),
       ...(result.appName ? { appName: result.appName } : {}),
       ...(result.appBundleId ? { appBundleId: result.appBundleId } : {}),
       ...(result.startup ? { startup: result.startup } : {}),

src/client-types.ts

@@ -184,6 +184,7 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
 
 export type AppOpenResult = {
   session: string;
+  sessionStateDir?: string;
   appName?: string;
   appBundleId?: string;
   appId?: string;

src/client.ts

@@ -152,6 +152,7 @@ export function createAgentDeviceClient(
         const appId = appBundleId;
         return {
           session,
+          sessionStateDir: readOptionalString(data, 'sessionStateDir'),
           appName: readOptionalString(data, 'appName'),
           appBundleId,
           appId,

src/commands/__tests__/client-output.test.ts

@@ -1,7 +1,39 @@
 import { describe, expect, test } from 'vitest';
-import { recordCliOutput } from '../client-output.ts';
+import { openCliOutput, recordCliOutput } from '../client-output.ts';
+
+describe('openCliOutput', () => {
+  test('prints session state directory on a second line', () => {
+    const output = openCliOutput({
+      session: 'default',
+      sessionStateDir: '/tmp/agent-device/sessions/cwd_123_default',
+      identifiers: { session: 'default' },
+    });
+
+    expect(output.text).toBe(
+      ['Opened: default', 'Session state: /tmp/agent-device/sessions/cwd_123_default'].join('\n'),
+    );
+    expect(output.data).toMatchObject({
+      session: 'default',
+      sessionStateDir: '/tmp/agent-device/sessions/cwd_123_default',
+    });
+  });
+});
 
 describe('recordCliOutput', () => {
+  test('prints session state directory for record-created sessions', () => {
+    const output = recordCliOutput({
+      recording: 'started',
+      outPath: '/tmp/recording.mp4',
+      sessionStateDir: '/tmp/agent-device/sessions/cwd_123_default',
+    });
+
+    expect(output.text).toBe(
+      ['/tmp/recording.mp4', 'Session state: /tmp/agent-device/sessions/cwd_123_default'].join(
+        '\n',
+      ),
+    );
+  });
+
   test('prints chunked Android recording paths clearly for human stdout', () => {
     const output = recordCliOutput({
       recording: 'stopped',

src/commands/client-output.ts

@@ -56,7 +56,12 @@ export function sessionCliOutput(result: { sessions: AgentDeviceSession[] }): Cl
 }
 
 export function openCliOutput(result: AppOpenResult): CliOutput {
-  return messageOutput(serializeOpenResult(result));
+  const data = serializeOpenResult(result);
+  const lines = [readCommandMessage(data)].filter((line): line is string => Boolean(line));
+  if (typeof data.sessionStateDir === 'string') {
+    lines.push(`Session state: ${data.sessionStateDir}`);
+  }
+  return { data, text: lines.join('\n') || null };
 }
 
 export function closeCliOutput(result: AppCloseResult | SessionCloseResult): CliOutput {
@@ -207,6 +212,8 @@ function defaultCommandCliOutput(result: CommandRequestResult): CliOutput {
 function formatRecordSingleOutput(data: Record<string, unknown>, outPath: string): string {
   const lines: string[] = [];
   if (outPath) lines.push(outPath);
+  if (typeof data.sessionStateDir === 'string')
+    lines.push(`Session state: ${data.sessionStateDir}`);
   if (typeof data.warning === 'string') lines.push(`Warning: ${data.warning}`);
   if (typeof data.overlayWarning === 'string')
     lines.push(`Overlay warning: ${data.overlayWarning}`);

src/contracts.ts

@@ -43,6 +43,7 @@ export type DaemonRequestMeta = {
   requestId?: string;
   debug?: boolean;
   cwd?: string;
+  sessionExplicit?: boolean;
   tenantId?: string;
   runId?: string;
   leaseId?: string;
@@ -348,6 +349,7 @@ export const daemonCommandRequestSchema = schema<DaemonRequest>((input, path) =>
             requestId: optionalString(meta, 'requestId', `${path}.meta`),
             debug: optionalBoolean(meta, 'debug', `${path}.meta`),
             cwd: optionalString(meta, 'cwd', `${path}.meta`),
+            sessionExplicit: optionalBoolean(meta, 'sessionExplicit', `${path}.meta`),
             tenantId: optionalString(meta, 'tenantId', `${path}.meta`),
             runId: optionalString(meta, 'runId', `${path}.meta`),
             leaseId: optionalString(meta, 'leaseId', `${path}.meta`),

src/daemon-client.ts

@@ -29,6 +29,7 @@ import {
 import { uploadArtifact } from './upload-client.ts';
 import { computeDaemonCodeSignature } from './daemon/code-signature.ts';
 import { PUBLIC_COMMANDS } from './command-catalog.ts';
+import { shellQuote } from './utils/shell-quote.ts';
 import {
   readDaemonHttpProgressResponse,
   shouldReadDaemonProgressStream,
@@ -157,6 +158,7 @@ export async function sendToDaemon(req: Omit<DaemonRequest, 'token'>): Promise<D
       requestId,
       debug,
       cwd: req.meta?.cwd,
+      sessionExplicit: req.meta?.sessionExplicit,
       tenantId: req.meta?.tenantId ?? req.flags?.tenant,
       runId: req.meta?.runId ?? req.flags?.runId,
       leaseId: req.meta?.leaseId ?? req.flags?.leaseId,
@@ -1783,11 +1785,19 @@ 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)}`;
 }