fix: clarify ios runner recovery errors

Author: thymikee

src/platforms/ios/__tests__/runner-command-retry.test.ts

@@ -213,6 +213,86 @@ test('read-only commands retry when completed status has no retained response',
   assert.equal(mockExecuteRunnerCommandWithSession.mock.calls[2]?.[2].command, 'snapshot');
 });
 
+test('mutating commands report recovery guidance when completed status has no retained response', async () => {
+  const session = makeRunnerSession({ port: 8100, ready: true });
+
+  mockEnsureRunnerSession.mockResolvedValueOnce(session);
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({ lifecycleState: 'completed' });
+
+  await assert.rejects(
+    () => runIosRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /"tap" completed after the transport response was lost/);
+      assert.equal(error.details?.recovery, 'completed_without_retained_response');
+      assert.match(String(error.details?.hint), /will not replay/);
+      assert.match(String(error.details?.hint), /snapshot -i/);
+      assert.equal(error.details?.transportError, 'fetch failed');
+      return true;
+    },
+  );
+
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls.length, 2);
+});
+
+test('mutating commands preserve runner failure details from status recovery', async () => {
+  const session = makeRunnerSession({ port: 8100, ready: true });
+
+  mockEnsureRunnerSession.mockResolvedValueOnce(session);
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({
+      lifecycleState: 'failed',
+      lifecycleErrorCode: 'AMBIGUOUS_MATCH',
+      lifecycleErrorMessage: 'Found 2 matching buttons',
+      lifecycleErrorHint: 'Use a more specific selector.',
+    });
+
+  await assert.rejects(
+    () => runIosRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'AMBIGUOUS_MATCH');
+      assert.equal(error.message, 'Found 2 matching buttons');
+      assert.equal(error.details?.recovery, 'runner_reported_failure');
+      assert.equal(error.details?.hint, 'Use a more specific selector.');
+      assert.equal(error.details?.transportError, 'fetch failed');
+      return true;
+    },
+  );
+
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls.length, 2);
+});
+
+test('mutating commands report wait-and-inspect guidance when status shows in-flight work', async () => {
+  const session = makeRunnerSession({ port: 8100, ready: true });
+
+  mockEnsureRunnerSession.mockResolvedValueOnce(session);
+  mockExecuteRunnerCommandWithSession
+    .mockRejectedValueOnce(new AppError('COMMAND_FAILED', 'fetch failed'))
+    .mockResolvedValueOnce({ lifecycleState: 'started' });
+
+  await assert.rejects(
+    () => runIosRunnerCommand(IOS_SIMULATOR, { command: 'tap', x: 120, y: 240 }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.match(error.message, /"tap" is still started/);
+      assert.equal(error.details?.recovery, 'command_still_in_flight');
+      assert.match(String(error.details?.hint), /may still finish/);
+      assert.match(String(error.details?.hint), /snapshot -i/);
+      assert.equal(error.details?.transportError, 'fetch failed');
+      return true;
+    },
+  );
+
+  assert.equal(mockInvalidateRunnerSession.mock.calls.length, 0);
+  assert.equal(mockExecuteRunnerCommandWithSession.mock.calls.length, 2);
+});
+
 test('mutating commands invalidate the retry session without replaying again', async () => {
   const staleSession = makeRunnerSession({ port: 8100, ready: true });
   const freshSession = makeRunnerSession({ port: 8101, ready: false });

src/platforms/ios/runner-client.ts

@@ -273,11 +273,13 @@ async function tryRecoverRunnerCommandAfterTransportError(
     }
     throw new AppError(
       'COMMAND_FAILED',
-      'Runner command completed, but its response was not retained for recovery.',
+      `Runner command "${command.command}" completed after the transport response was lost, but no recoverable response was retained.`,
       {
         command: command.command,
         commandId: command.commandId,
         lifecycleState,
+        recovery: 'completed_without_retained_response',
+        hint: completedWithoutRetainedResponseHint(command.command),
         logPath: options.logPath,
         transportError: transportError.message,
       },
@@ -301,7 +303,8 @@ async function tryRecoverRunnerCommandAfterTransportError(
         command: command.command,
         commandId: command.commandId,
         lifecycleState,
-        hint,
+        recovery: 'runner_reported_failure',
+        hint: hint ?? runnerReportedFailureHint(command.command),
         logPath: options.logPath,
         transportError: transportError.message,
       },
@@ -312,11 +315,13 @@ async function tryRecoverRunnerCommandAfterTransportError(
   if (lifecycleState === 'accepted' || lifecycleState === 'started') {
     throw new AppError(
       'COMMAND_FAILED',
-      `Runner command is ${lifecycleState}, but its response was lost.`,
+      `Runner command "${command.command}" is still ${lifecycleState} after the transport response was lost.`,
       {
         command: command.command,
         commandId: command.commandId,
         lifecycleState,
+        recovery: 'command_still_in_flight',
+        hint: inFlightAfterLostResponseHint(command.command),
         logPath: options.logPath,
         transportError: transportError.message,
       },
@@ -343,6 +348,18 @@ function parseLifecycleResponseJson(value: unknown): Record<string, unknown> | u
   return {};
 }
 
+function completedWithoutRetainedResponseHint(command: string): string {
+  return `The runner reports "${command}" already completed, so agent-device will not replay it. Run snapshot -i to inspect the current UI, then continue from that observed state. If the session is stale, close and reopen the session before retrying.`;
+}
+
+function runnerReportedFailureHint(command: string): string {
+  return `The runner observed "${command}" fail after the transport response was lost, so agent-device did not replay it. Run snapshot -i to inspect the current UI and retry with a selector visible in that snapshot. If the session is stale, close and reopen the session before retrying.`;
+}
+
+function inFlightAfterLostResponseHint(command: string): string {
+  return `The runner has accepted "${command}" and it may still finish, so agent-device will not replay it. Wait briefly, run snapshot -i to inspect the current UI, then continue from that observed state. If the session stops responding, close and reopen the session before retrying.`;
+}
+
 function isRunnerReadinessPreflightError(error: AppError): boolean {
   return error.details?.runnerReadinessPreflightFailed === true;
 }