Merge remote-tracking branch 'origin/main' into claude/wait-poll-timeline

* origin/main:
  fix(ios): stop charging every capture for a slow Simulator app discovery (#2331)
  refactor(commands): move commands-side rendering out of src/daemon and retire the doctor progress flag (#2349)

# Conflicts:
#	CHANGELOG.md

Author: thymikee

CHANGELOG.md

@@ -8,6 +8,13 @@
   runner-restart) next to the unchanged `reason`, so a failure says where its budget went without
   opening the request log. Long waits keep the first five and last twenty-five polls. `wait
   --stable` timeouts and a never-readable strict absence keep their existing diagnostics.
+- Fixed: the iOS Simulator AX snapshot route bounds how long a capture waits for app discovery
+  and stops starting a discovery per capture. Discovery (`simctl launchctl list` through xcrun)
+  takes seconds on a loaded host; a capture now waits at most 1.5s for the one in-flight
+  discovery, takes the XCTest fallback, and the discovery keeps running under its own 15s
+  deadline for the captures that follow. Previously each capture ran its own probe with a 3s
+  timeout on its critical path, so a `wait` issued right after `open` could spend its budget on
+  probe timeouts and report `wait_capture_stalled` with the app already on screen.
 - Fixed: iOS snapshots no longer report `truncated: true` merely because a later backend produced
   them. The runner stamped every recovered capture as truncated — including a complete private-AX
   tree taken while the XCTest channel was penalized as slow — so a strict `is absent` / `wait absent`

packages/platform-apple/src/snapshot-route.test.ts

@@ -1,8 +1,10 @@
 import { expect, test, vi } from 'vitest';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { areIosSnapshotComparisonIdentitiesEqual } from '@agent-device/capture-kit/ios-snapshot-planning';
+import { createLocalAppleToolProvider, withAppleToolProvider } from './core/tool-provider.ts';
 import { platformRuntimeHostFixture } from './runtime.fixtures.ts';
 import { createAppleSnapshotRoute } from './snapshot-route.ts';
+import { createSimulatorSnapshotTargetResolver } from './snapshot-target.ts';
 import type { SimulatorSnapshotSource, SnapshotSourceOutcome } from './snapshot-source-facade.ts';
 
 const ios = {
@@ -202,6 +204,68 @@ test('cancelled acquisition does not start a fallback after the request aborts',
   expect(fallback).not.toHaveBeenCalled();
 });
 
+test('a slow app discovery yields to the XCTest fallback within its wait slice, then serves the bridge', async () => {
+  // The production resolver over a simctl whose `launchctl list` answers only when released,
+  // the shape of a loaded CI host: the first capture must not sit on that probe.
+  let release!: () => void;
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const run = vi.fn(async (args: string[]) => {
+    if (args[0] === 'spawn') await released;
+    return {
+      stdout:
+        args[0] === 'spawn'
+          ? `42\t0\tUIKitApplication:${input.options.appBundleId}[launch-a][rb-legacy]`
+          : JSON.stringify({
+              devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-26-0': [{ udid: ios.id }] },
+            }),
+      stderr: '',
+      exitCode: 0,
+    };
+  });
+  const runCommand = vi.fn(async () => ({ stdout: 'start-a', stderr: '', exitCode: 0 }));
+  const fallback = vi.fn(async () => runnerResult());
+  const source = sourceReturning(bridgeAcquisition());
+  const presentIosAcquisition = vi.fn(async () => ({
+    backend: 'xctest' as const,
+    producer: 'simulator-ax-bridge' as const,
+    nodes: [{ index: 0, type: 'Application' }],
+  }));
+  const route = createAppleSnapshotRoute(
+    {
+      ...platformRuntimeHostFixture(),
+      snapshot: { captureSurface: vi.fn(), presentIosAcquisition },
+    },
+    { source, resolveTarget: createSimulatorSnapshotTargetResolver() },
+  );
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(
+      createLocalAppleToolProvider({ simctl: { run }, runCommand }),
+      async () => {
+        const first = route.capture(ios, input, signal(), fallback);
+        await vi.advanceTimersByTimeAsync(1_500);
+        const result = await first;
+        expect(fallback).toHaveBeenCalledOnce();
+        expect(result.warnings).toEqual([
+          'Simulator AX snapshot unavailable (target-resolution-failed); used XCTest for an unverified app generation.',
+        ]);
+        expect(source.acquire).not.toHaveBeenCalled();
+
+        release();
+        await vi.advanceTimersByTimeAsync(0);
+        const second = await route.capture(ios, input, signal(), fallback);
+        expect(second.producer).toBe('simulator-ax-bridge');
+        expect(fallback).toHaveBeenCalledOnce();
+        expect(run.mock.calls.filter(([args]) => args[0] === 'spawn')).toHaveLength(1);
+      },
+    );
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
 function bridgeAcquisition(): Extract<SnapshotSourceOutcome, { stage: 'acquired' }> {
   return {
     stage: 'acquired',

packages/platform-apple/src/snapshot-target.test.ts

@@ -17,7 +17,7 @@ const signal = () => new AbortController().signal;
 
 function targetFixture() {
   const state = { pid: 42, launch: 'launch-a', start: 'start-a' as string | null };
-  const run = vi.fn(async (args: string[]) => ({
+  const run = vi.fn(async (args: string[], _options?: { timeoutMs?: number }) => ({
     stdout:
       args[0] === 'spawn'
         ? `90\t0\tUIKitApplication:com.example.app.beta[wrong][rb-legacy]\n${state.pid}\t0\tUIKitApplication:${app}[${state.launch}][rb-legacy]`
@@ -27,11 +27,13 @@ function targetFixture() {
     stderr: '',
     exitCode: 0,
   }));
-  const runCommand = vi.fn(async () => ({
-    stdout: state.start ?? '',
-    stderr: '',
-    exitCode: state.start ? 0 : 1,
-  }));
+  const runCommand = vi.fn(
+    async (_tool: string, _args: string[], _options?: { timeoutMs?: number }) => ({
+      stdout: state.start ?? '',
+      stderr: '',
+      exitCode: state.start ? 0 : 1,
+    }),
+  );
   const provider = createLocalAppleToolProvider({ simctl: { run }, runCommand });
   const resolve = createSimulatorSnapshotTargetResolver();
   return {
@@ -137,3 +139,127 @@ test('an aborted request cannot reuse a cached target', async () => {
     expect(fixture.runCommand).toHaveBeenCalledTimes(1);
   });
 });
+
+function deferredSpawn(fixture: ReturnType<typeof targetFixture>) {
+  let release!: () => void;
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const respond = fixture.run.getMockImplementation()!;
+  fixture.run.mockImplementation(async (args: string[]) =>
+    args[0] === 'spawn' ? await released.then(() => respond(args)) : await respond(args),
+  );
+  return release;
+}
+
+test('a slow discovery yields to the fallback after its wait budget and finishes in the background', async () => {
+  const fixture = targetFixture();
+  const release = deferredSpawn(fixture);
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(fixture.provider, async () => {
+      const pending = fixture.resolve(ios, app, signal());
+      const rejected = expect(pending).rejects.toMatchObject({
+        details: { reason: 'simulator-target-discovery-pending' },
+      });
+      await vi.advanceTimersByTimeAsync(1_500);
+      await rejected;
+      expect(fixture.discoveryCount()).toBe(1);
+
+      release();
+      await vi.advanceTimersByTimeAsync(0);
+      // The finished discovery serves the next capture without a second simctl spawn.
+      expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
+      expect(fixture.discoveryCount()).toBe(1);
+    });
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('captures that arrive during discovery join it instead of spawning their own', async () => {
+  const fixture = targetFixture();
+  const release = deferredSpawn(fixture);
+  await withAppleToolProvider(fixture.provider, async () => {
+    const first = fixture.resolve(ios, app, signal());
+    const second = fixture.resolve(ios, app, signal());
+    release();
+    const targets = await Promise.all([first, second]);
+    expect(targets[1]).toBe(targets[0]);
+    expect(fixture.discoveryCount()).toBe(1);
+  });
+});
+
+test('a cancelled caller leaves discovery running for the next capture', async () => {
+  const fixture = targetFixture();
+  const release = deferredSpawn(fixture);
+  await withAppleToolProvider(fixture.provider, async () => {
+    const controller = new AbortController();
+    const cancelled = fixture.resolve(ios, app, controller.signal);
+    controller.abort(new Error('request-ended'));
+    await expect(cancelled).rejects.toThrow('request-ended');
+
+    release();
+    expect(await fixture.resolve(ios, app, signal())).toMatchObject({ pid: 42 });
+    expect(fixture.discoveryCount()).toBe(1);
+  });
+});
+
+test('one discovery shares a single deadline across its simctl probes and the identity read', async () => {
+  const fixture = targetFixture();
+  const release = deferredSpawn(fixture);
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(fixture.provider, async () => {
+      const pending = fixture.resolve(ios, app, signal());
+      pending.catch(() => undefined);
+      // The spawn ran 13s of the 15s discovery deadline before answering.
+      await vi.advanceTimersByTimeAsync(13_000);
+      release();
+      await vi.advanceTimersByTimeAsync(0);
+      await expect(fixture.resolve(ios, app, signal())).resolves.toMatchObject({ pid: 42 });
+
+      const spawnOptions = fixture.run.mock.calls.find(([args]) => args[0] === 'spawn')?.[1];
+      expect(spawnOptions?.timeoutMs).toBe(15_000);
+      const identityOptions = fixture.runCommand.mock.calls[0]?.[2];
+      expect(identityOptions?.timeoutMs).toBeGreaterThan(0);
+      expect(identityOptions?.timeoutMs).toBeLessThanOrEqual(2_000);
+    });
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test('a failed runtime probe does not release the slot while the launch-job probe still runs', async () => {
+  const fixture = targetFixture();
+  const release = deferredSpawn(fixture);
+  const respond = fixture.run.getMockImplementation()!;
+  fixture.run.mockImplementation(async (args: string[], options) =>
+    args[0] === 'list'
+      ? { stdout: '', stderr: 'simctl list failed', exitCode: 1 }
+      : await respond(args, options),
+  );
+  vi.useFakeTimers();
+  try {
+    await withAppleToolProvider(fixture.provider, async () => {
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const pending = fixture.resolve(ios, app, signal());
+        const rejected = expect(pending).rejects.toMatchObject({
+          details: { reason: 'simulator-target-discovery-pending' },
+        });
+        await vi.advanceTimersByTimeAsync(1_500);
+        await rejected;
+      }
+      expect(fixture.discoveryCount()).toBe(1);
+
+      release();
+      await vi.advanceTimersByTimeAsync(0);
+      // The settled discovery reports the runtime failure and frees the slot for a fresh probe.
+      await expect(fixture.resolve(ios, app, signal())).rejects.toMatchObject({
+        details: { reason: 'simulator-runtime-probe-failed' },
+      });
+    });
+  } finally {
+    vi.useRealTimers();
+  }
+});