fix(ios): recover simulator recorder startup failures (#2447)

Co-authored-by: PLASMA-FR <173463847+PLASMA-FR@users.noreply.github.com>

Author: PLASMA-FR

src/commands/recording/index.ts

@@ -104,7 +104,7 @@ export const recordCommandFacet = defineCommandFacet({
   text: {
     summary: 'Start or stop screen recording',
     cliDetail:
-      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends.',
+      'The default --scope app requires an active app session from open <app>; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service.',
   },
   metadata: recordCommandMetadata,
   run: (client, input) => client.recording.record(input as RecordOptions),

src/platform-runtime-screen-recording-apple-simulator-host.test.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { beforeEach, expect, test, vi } from 'vitest';
+import { normalizeError } from '@agent-device/kernel/errors';
 import { mkdtempForTestSync } from './__tests__/test-utils/tmp-dir.ts';
 import { createAppleScreenRecordingHost } from './platform-runtime-screen-recording-apple-host.ts';
 import { startAppleSimulatorRecording } from './platform-runtime-screen-recording-apple-simulator-host.ts';
@@ -46,6 +47,89 @@ beforeEach(() => {
   processes.commands.clear();
 });
 
+test.each([
+  { exitCode: 16, pid: 43, hasIdentity: true, code: 'DEVICE_IN_USE' },
+  { exitCode: 16, pid: 43, hasIdentity: false, code: 'DEVICE_IN_USE' },
+  { exitCode: 16, pid: undefined, hasIdentity: false, code: 'DEVICE_IN_USE' },
+  { exitCode: 1, pid: 43, hasIdentity: true, code: 'UNKNOWN' },
+  { exitCode: 1, pid: 43, hasIdentity: false, code: 'UNKNOWN' },
+  { exitCode: 1, pid: undefined, hasIdentity: false, code: 'UNKNOWN' },
+])(
+  'classifies recorder exit $exitCode with pid=$pid and identity=$hasIdentity',
+  async ({ exitCode, pid, hasIdentity, code }) => {
+    const root = mkdtempForTestSync('agent-device-recording-busy-');
+    const failed = background(pid);
+    const stderr =
+      'Error starting video recorder: Error Domain=NSPOSIXErrorDomain Code=16 "Resource busy"\nNSLocalizedFailureReason=Host recording is already in progress';
+    failed.resolveWait({ stdout: '', stderr, exitCode });
+    if (!hasIdentity) {
+      processes.starts.clear();
+      processes.commands.clear();
+    }
+
+    const error = await withTransport(
+      failed.process,
+      async () =>
+        await createAppleScreenRecordingHost().startSimulator(
+          simulator,
+          path.join(root, 'failed.mp4'),
+        ),
+    ).then(() => {
+      throw new Error('unexpected recording start');
+    }, normalizeError);
+
+    expect(error.code).toBe(code);
+    if (exitCode === 16) {
+      expect(error).toMatchObject({
+        retriable: false,
+        hint: expect.stringContaining('CoreSimulator'),
+        details: { reason: 'apple_simulator_recording_busy', exitCode, stderr },
+      });
+      expect(error.hint).toContain('record stop');
+    } else {
+      expect(error.details?.reason).toBeUndefined();
+    }
+  },
+);
+
+test('classifies a recorder exit that settles during the final identity poll', async () => {
+  vi.useFakeTimers();
+  const failed = background(43);
+  const readStart = vi.spyOn(processes.starts, 'get');
+  const identityPolls = 2_000 / 25 + 1;
+  readStart.mockImplementation(() => {
+    if (readStart.mock.calls.length === identityPolls) {
+      failed.resolveWait({
+        stdout: '',
+        stderr: 'Host recording is already in progress',
+        exitCode: 16,
+      });
+    }
+    return undefined;
+  });
+  try {
+    const root = mkdtempForTestSync('agent-device-recording-identity-deadline-');
+    const starting = withTransport(
+      failed.process,
+      async () => await startAppleSimulatorRecording(simulator, path.join(root, 'failed.mp4')),
+    ).then(() => {
+      throw new Error('unexpected recording start');
+    }, normalizeError);
+
+    await vi.waitFor(() => expect(readStart).toHaveBeenCalled());
+    await vi.runAllTimersAsync();
+    expect(readStart).toHaveBeenCalledTimes(identityPolls);
+    expect(await starting).toMatchObject({
+      code: 'DEVICE_IN_USE',
+      details: { reason: 'apple_simulator_recording_busy', exitCode: 16 },
+    });
+    expect(failed.kill).toHaveBeenCalledWith('SIGINT');
+  } finally {
+    readStart.mockRestore();
+    vi.useRealTimers();
+  }
+});
+
 test('waits for delayed output and rejects an early nonzero exit', async () => {
   const root = mkdtempForTestSync('agent-device-recording-ready-');
   const outputPath = path.join(root, 'capture.mp4');
@@ -109,7 +193,7 @@ test('late provider acquisition after abort is rolled back exactly once', async
   await expect(starting).rejects.toBe(reason);
   resolveStart?.(late.process);
   await vi.waitFor(() => expect(late.kill).toHaveBeenCalledTimes(1));
-  expect(late.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(late.kill).toHaveBeenCalledWith('SIGINT');
 });
 
 test('resolved provider acquisition aborted before publication removes partial output and settles', async () => {
@@ -134,7 +218,7 @@ test('resolved provider acquisition aborted before publication removes partial o
 
   await expect(starting).rejects.toBe(reason);
   expect(acquired.kill).toHaveBeenCalledTimes(1);
-  expect(acquired.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(acquired.kill).toHaveBeenCalledWith('SIGINT');
   expect(fs.existsSync(outputPath)).toBe(false);
 });
 
@@ -242,7 +326,30 @@ test('pidless provider process is killed and settled before start fails', async
       async () => await startAppleSimulatorRecording(simulator, '/tmp/pidless.mp4'),
     ),
   ).rejects.toThrow('complete process identity');
-  expect(running.kill).toHaveBeenCalledWith('SIGKILL');
+  expect(running.kill).toHaveBeenCalledWith('SIGINT');
+});
+
+test('unpublished recorder cleanup gives SIGINT a grace window before forcing exit', async () => {
+  vi.useFakeTimers();
+  try {
+    const running = background(undefined);
+    running.kill.mockImplementationOnce(() => true);
+    const starting = withTransport(
+      running.process,
+      async () => await startAppleSimulatorRecording(simulator, '/tmp/stalled-provider.mp4'),
+    );
+    const rejected = expect(starting).rejects.toThrow('complete process identity');
+
+    await vi.waitFor(() => expect(running.kill).toHaveBeenCalledWith('SIGINT'));
+    await vi.advanceTimersByTimeAsync(4_000);
+    expect(running.kill).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await rejected;
+    expect(running.kill.mock.calls).toEqual([['SIGINT'], ['SIGKILL']]);
+    expect(vi.getTimerCount()).toBe(0);
+  } finally {
+    vi.useRealTimers();
+  }
 });
 
 function background(pid: number | undefined, command?: string) {

src/platform-runtime-screen-recording-apple-simulator-host.ts

@@ -1,4 +1,6 @@
 import fs from 'node:fs';
+import { execFailureDetails } from '@agent-device/host-kit/command';
+import { AppError } from '@agent-device/kernel/errors';
 import type {
   HostCommandResult,
   ManagedProcessIdentity,
@@ -19,6 +21,7 @@ const LIVENESS_GRACE_MS = 50;
 const READY_TIMEOUT_MS = 15_000;
 const IDENTITY_POLL_MS = 25;
 const IDENTITY_TIMEOUT_MS = 2_000;
+const UNPUBLISHED_STOP_GRACE_MS = 5_000;
 
 const appleSimulatorRecordingCommandMatches: ManagedProcessCommandMatcher = (
   persisted,
@@ -62,13 +65,12 @@ export async function startAppleSimulatorRecording(
   if (!background) throw new Error('simctl recordVideo acquisition did not return a process');
   let rootMarker: ManagedProcessIdentity | undefined;
   try {
-    rootMarker = await waitForManagedProcessIdentity(background.child.pid, signal);
+    rootMarker = await waitForManagedProcessIdentity(background.child.pid, background.wait, signal);
     if (!rootMarker) {
       throw new Error('simctl recordVideo did not expose a complete process identity');
     }
   } catch (error) {
-    background.child.kill('SIGKILL');
-    await background.wait.catch(() => undefined);
+    await rollbackAcquiredSimulatorProcess(background);
     signal?.throwIfAborted();
     throw error;
   }
@@ -96,15 +98,22 @@ export async function startAppleSimulatorRecording(
 
 async function waitForManagedProcessIdentity(
   pid: number | undefined,
+  wait: Promise<HostCommandResult>,
   signal?: AbortSignal,
 ): Promise<ManagedProcessIdentity | undefined> {
-  if (pid === undefined) return undefined;
-  const attempts = Math.ceil(IDENTITY_TIMEOUT_MS / IDENTITY_POLL_MS);
+  const processExit = observeSimulatorExit(wait);
+  const attempts = pid === undefined ? 0 : Math.ceil(IDENTITY_TIMEOUT_MS / IDENTITY_POLL_MS);
   for (let attempt = 0; attempt <= attempts; attempt += 1) {
     signal?.throwIfAborted();
     const marker = await resolveManagedProcessIdentity(pid);
     if (marker) return marker;
-    if (attempt < attempts) await delay(IDENTITY_POLL_MS, signal);
+    const exit = await Promise.race([
+      processExit,
+      attempt < attempts
+        ? delay(IDENTITY_POLL_MS, signal).then(() => undefined)
+        : Promise.resolve(undefined),
+    ]);
+    if (exit) throw startError(exit);
   }
   return undefined;
 }
@@ -116,7 +125,7 @@ async function acquireSimulatorProcess(
   const started = Promise.resolve(acquisition);
   if (!signal) return await started;
   if (signal.aborted) {
-    if (isSimulatorProcess(acquisition)) {
+    if ('child' in acquisition) {
       await rollbackAcquiredSimulatorProcess(acquisition);
     } else {
       void started.then(rollbackAcquiredSimulatorProcess);
@@ -141,17 +150,24 @@ async function acquireSimulatorProcess(
   }
 }
 
-function isSimulatorProcess(
-  value: AppleSimulatorScreenRecordingProcess | Promise<AppleSimulatorScreenRecordingProcess>,
-): value is AppleSimulatorScreenRecordingProcess {
-  return 'child' in value;
-}
-
 async function rollbackAcquiredSimulatorProcess(
   process: AppleSimulatorScreenRecordingProcess,
 ): Promise<void> {
-  process.child.kill('SIGKILL');
-  await process.wait.catch(() => undefined);
+  // CONSERVATIVE: Give simctl time to detach from CoreSimulator before forcing exit;
+  // revisit only when the transport can explicitly acknowledge detachment.
+  process.child.kill('SIGINT');
+  const grace = new AbortController();
+  const settled = await Promise.race([
+    process.wait.then(
+      () => true,
+      () => true,
+    ),
+    delay(UNPUBLISHED_STOP_GRACE_MS, grace.signal).then(() => false),
+  ]).finally(() => grace.abort());
+  if (!settled) {
+    process.child.kill('SIGKILL');
+    await process.wait.catch(() => undefined);
+  }
 }
 
 function createAppleSimulatorProcess(
@@ -203,10 +219,7 @@ async function waitForReadiness(
   wait: Promise<HostCommandResult>,
   signal?: AbortSignal,
 ): Promise<void> {
-  const processExit = wait.then(
-    (result) => ({ kind: 'exited' as const, result }),
-    (error: unknown) => ({ kind: 'failed' as const, error }),
-  );
+  const processExit = observeSimulatorExit(wait);
   let settled: AppleSimulatorExit | undefined;
   void processExit.then((outcome) => {
     settled = outcome;
@@ -235,11 +248,33 @@ async function waitForReadiness(
   }
 }
 
+function observeSimulatorExit(wait: Promise<HostCommandResult>): Promise<AppleSimulatorExit> {
+  return wait.then(
+    (result) => ({ kind: 'exited' as const, result }),
+    (error: unknown) => ({ kind: 'failed' as const, error }),
+  );
+}
+
 function startError(outcome: AppleSimulatorExit): Error {
   if (outcome.kind === 'failed') {
     return outcome.error instanceof Error ? outcome.error : new Error(String(outcome.error));
   }
-  return new Error(`simctl recordVideo exited with code ${outcome.result.exitCode}`);
+  const { exitCode } = outcome.result;
+  if (exitCode === 16) {
+    return new AppError(
+      'DEVICE_IN_USE',
+      'CoreSimulator host recording is already in progress',
+      execFailureDetails(
+        { ...outcome.result, exitCode },
+        {
+          reason: 'apple_simulator_recording_busy',
+          retriable: false,
+          hint: 'Stop the active recording with record stop in its owning session. If a previous recorder died and no recording is active, ask the host operator to restart the CoreSimulator stream service before retrying.',
+        },
+      ),
+    );
+  }
+  return new Error(`simctl recordVideo exited with code ${exitCode}`);
 }
 
 function delay(milliseconds: number, signal?: AbortSignal): Promise<void> {

test/integration/provider-scenarios/ios-record-trace.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { test } from 'vitest';
+import { runCmdBackground } from '@agent-device/host-kit/command';
 import type { AppleSimulatorScreenRecordingTransport } from '../../../src/platform-runtime-screen-recording-apple-transport.ts';
 import {
   assertFlatToolCallStartsWith,
@@ -60,7 +61,7 @@ test('generic scoped iOS physical runner recording fails closed without local fa
   );
 });
 
-test('Provider-backed integration iOS simulator recording flow uses the focused Apple transport', async () => {
+test('iOS simulator recording reports host contention and recovers through the focused Apple transport', async () => {
   await withProviderScenarioTempDir(
     'agent-device-provider-scenario-ios-sim-record-',
     async (tmpDir) => {
@@ -83,6 +84,16 @@ test('Provider-backed integration iOS simulator recording flow uses the focused
         start: ({ device, outputPath }) => {
           assert.equal(device.id, PROVIDER_SCENARIO_IOS_SIMULATOR.id);
           recordingStarts.push(outputPath);
+          if (recordingStarts.length === 1) {
+            return runCmdBackground(
+              process.execPath,
+              [
+                '-e',
+                'process.stderr.write("Host recording is already in progress"); process.exit(16)',
+              ],
+              { allowFailure: true },
+            );
+          }
           return createProviderIosSimulatorRecordingProcess(outputPath, (signal) => {
             recordingSignals.push(signal);
           });
@@ -108,6 +119,21 @@ test('Provider-backed integration iOS simulator recording flow uses the focused
         assert.equal(open.statusCode, 200, JSON.stringify(open.json));
         assert.equal(open.json?.error, undefined, JSON.stringify(open.json));
 
+        const busyStart = await daemon.callCommand('record', ['start', recordingPath], {
+          hideTouches: true,
+        });
+        assert.equal(busyStart.json?.error?.data?.code, 'DEVICE_IN_USE');
+        assert.equal(busyStart.json?.error?.data?.retriable, false);
+        assert.equal(
+          busyStart.json?.error?.data?.details?.reason,
+          'apple_simulator_recording_busy',
+        );
+        assert.equal(busyStart.json?.error?.data?.details?.exitCode, 16);
+        assert.match(busyStart.json?.error?.data?.hint ?? '', /record stop/);
+        assert.match(busyStart.json?.error?.data?.hint ?? '', /CoreSimulator/);
+        assert.equal(daemon.session()?.screenRecording, undefined);
+        assert.equal(fs.existsSync(recordingPath), false);
+
         const recordStart = await daemon.callCommand(
           'record',
           ['start', recordingPath],
@@ -143,7 +169,7 @@ test('Provider-backed integration iOS simulator recording flow uses the focused
         assert.equal(fs.existsSync(ownedProcessRecordPath), false);
 
         runnerTranscript.assertComplete();
-        assert.deepEqual(recordingStarts, [recordingPath]);
+        assert.deepEqual(recordingStarts, [recordingPath, recordingPath]);
         assert.deepEqual(recordingSignals, ['SIGINT']);
         assertFlatToolCallStartsWith(appleTool.calls, [
           'simctl',

website/docs/docs/commands.md

@@ -955,6 +955,7 @@ agent-device record stop                # Stop active recording
 - In `--json` mode, each overlay ref also includes a screenshot-space `center` point for coordinate fallback like `press <x> <y>`.
 - Burned-in touch overlays are exported only on macOS hosts, because the overlay pipeline depends on Swift + AVFoundation helpers.
 - On Linux or other non-macOS hosts, `record stop` still succeeds and returns the raw video plus telemetry sidecar, and includes `overlayWarning` when burn-in overlays were skipped.
+- On iOS simulators, a busy CoreSimulator host recording slot makes `record start` return non-retriable `DEVICE_IN_USE` with `details.reason: apple_simulator_recording_busy`. Use `record stop` in the session that owns the active recording. If a previous recorder died and no recording is active, ask the host operator to restart the CoreSimulator stream service before retrying.
 - Android uses `adb shell screenrecord`, which has a 180s platform limit. `record start` publishes a durable device manifest. Longer recordings are split into MP4 chunks while the daemon stays alive; after daemon restart, `record stop` recovers only manifest-owned chunks and warns when gesture overlay telemetry was lost.
 
 **Session app logs (token-efficient debugging):** Logging is off by default in normal flows. Enable it on demand for debugging. Logs are written to a file so agents can grep instead of loading full output into context.