fix(apple): read the launch confirmation whenever the open cannot see the app (#3115)

* fix(apple): read the launch confirmation whenever the open cannot see the app

An iOS Simulator open with --launch-url answered the "Open in <App>?" prompt
only when the post-open observation was `unobservable`. A target discovery that
failed on its own deadline, an open bridge circuit or a failed probe produced
`probe-failed`, the read was skipped, and the open returned green for a launch
that never happened; every later command then failed `app is not running`.

- `settleAppleOpen` reads the sheet on any verdict short of `observable`, and
  keeps the typed `postOpenObservationFailure` for a verdict the bridge could
  not produce.
- An answer attempt now reports its typed outcome instead of swallowing to
  `undefined`. Only an accept changes the device, so only its outcome is
  re-observed: when the app is then proven to have no process, the accept died
  with the runner session that raised it or the device dropped a held URL, and
  the open hands the same URL over once more and reads again.
- A launch still proven not running afterwards fails with
  `launch_confirmation_unanswered` rather than returning success.
- `LaunchObservation.unobservable` carries how it was proven, because only a
  settled target discovery proves no process; an expired launch-transition
  window proves only that the app was still coming up.
- Bounded `simctl openurl` (#3101): a CoreSimulator that never answers fails
  the open within 20s and kills the child, instead of the request being
  cancelled around a still-running `openurl`.

Closes #3096
Closes #3101

* docs(apple): state the launch-confirmation contract the settle acts on

* test(apple): cancel a running openurl through the request signal

The pre-seeded rejection only proved the catch rethrows a foreign failure. Drive
the abort for real so the forwarded `runnerOptions.signal` is what ends the
child, and keep the dispatch disclosure out of the producer: `open` is
declared `mutates-app`, so the daemon seam already answers `unknown` for a
failure no producer classified.

* test(apple): keep one source of truth for the confirmation shape

The review found three P3s on the same split:

- The openurl-timeout test compared `hint` against itself, so nothing pinned the
  operator-facing text. Export `IOS_SIMULATOR_OPENURL_TIMEOUT_HINT` and assert it.
- `CONFIRMATION` and `alertNotFound()` existed twice, one copy per test file, so
  prompt-text changes could diverge. Both now come from
  `launch-confirmation.fixtures.ts`, which `lifecycle.fixtures.ts` no longer
  duplicates.
- The docs claimed every later command would have failed; `open` and `activate`
  can relaunch a stopped app, so the claim is limited to commands that require a
  running app.

Author: thymikee

packages/platform-apple/src/core/__tests__/app-launch-url.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, test, vi } from 'vitest';
 import assert from 'node:assert/strict';
 import { IOS_TEST_SIMULATOR } from './apple-core-stub-helpers.ts';
-import { IOS_SIMULATOR_TERMINATE_TIMEOUT_MS } from '../config.ts';
+import { IOS_SIMULATOR_OPENURL_TIMEOUT_MS, IOS_SIMULATOR_TERMINATE_TIMEOUT_MS } from '../config.ts';
 
 vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@agent-device/host-kit/command')>();
@@ -12,9 +12,14 @@ vi.mock('../simulator.ts', async (importOriginal) => {
   return { ...actual, ensureBootedSimulator: vi.fn(actual.ensureBootedSimulator) };
 });
 
+import { AppError } from '@agent-device/kernel/errors';
 import { runCmd } from '@agent-device/host-kit/command';
 import { ensureBootedSimulator } from '../simulator.ts';
-import { openIosApp } from '../app-launch.ts';
+import {
+  IOS_SIMULATOR_OPENURL_TIMEOUT_HINT,
+  IOS_SIMULATOR_OPENURL_TIMEOUT_REASON,
+  openIosApp,
+} from '../app-launch.ts';
 
 const mockRunCmd = vi.mocked(runCmd);
 const mockEnsureBootedSimulator = vi.mocked(ensureBootedSimulator);
@@ -41,6 +46,51 @@ test('iOS simulator URL relaunch terminates the app before opening the URL', asy
         timeoutMs: IOS_SIMULATOR_TERMINATE_TIMEOUT_MS,
       },
     ],
-    ['xcrun', ['simctl', 'openurl', 'sim-1', 'myapp://automation'], undefined],
+    [
+      'xcrun',
+      ['simctl', 'openurl', 'sim-1', 'myapp://automation'],
+      { timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS },
+    ],
   ]);
 });
+
+test('a Simulator that never answers openurl fails the open at its own bound', async () => {
+  mockRunCmd.mockRejectedValueOnce(
+    new AppError('COMMAND_FAILED', 'xcrun timed out after 20000ms', { timeoutMs: 20_000 }),
+  );
+
+  const failure = await openIosApp(IOS_TEST_SIMULATOR, 'myapp://automation', {})
+    .then(() => undefined)
+    .catch((error: unknown) => error);
+
+  assert.ok(failure instanceof AppError);
+  assert.equal(failure.code, 'COMMAND_FAILED');
+  assert.deepEqual(failure.details, {
+    timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS,
+    reason: IOS_SIMULATOR_OPENURL_TIMEOUT_REASON,
+    deviceId: IOS_TEST_SIMULATOR.id,
+    hint: IOS_SIMULATOR_OPENURL_TIMEOUT_HINT,
+  });
+});
+
+test('a request canceled while openurl runs stays a canceled request, not a timeout', async () => {
+  const open = new AbortController();
+  mockRunCmd.mockImplementation(
+    (_cmd, _args, options) =>
+      new Promise((_resolve, reject) => {
+        options?.signal?.addEventListener('abort', () => reject(options.signal?.reason), {
+          once: true,
+        });
+      }),
+  );
+
+  const pending = openIosApp(IOS_TEST_SIMULATOR, 'myapp://automation', {
+    runnerOptions: { signal: open.signal },
+  }).catch((error: unknown) => error);
+
+  await vi.waitFor(() => assert.equal(mockRunCmd.mock.calls.length, 1));
+  const canceled = new AppError('COMMAND_FAILED', 'request canceled');
+  open.abort(canceled);
+
+  assert.equal(await pending, canceled);
+});

packages/platform-apple/src/core/__tests__/apps.test.ts

@@ -32,7 +32,7 @@ import { screenshotIos } from '../screenshot.ts';
 import { withMockedMacOsHelper } from './macos-helper-test-utils.ts';
 import { quitMacOsApp, resolveMacOsHelperPackageRootFrom } from '../../os/macos/helper.ts';
 import { ensureBootedSimulator } from '../simulator.ts';
-import { IOS_SIMULATOR_TERMINATE_TIMEOUT_MS } from '../config.ts';
+import { IOS_SIMULATOR_OPENURL_TIMEOUT_MS, IOS_SIMULATOR_TERMINATE_TIMEOUT_MS } from '../config.ts';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { runCmd } from '@agent-device/host-kit/command';
 import { retryWithPolicy } from '@agent-device/host-kit/retry';
@@ -407,7 +407,7 @@ test('openIosApp opens custom-scheme iOS simulator URLs directly when launch arg
   assert.deepEqual(mockRunCmd.mock.calls[0], [
     'xcrun',
     ['simctl', 'openurl', 'sim-1', 'myapp://item/42'],
-    undefined,
+    { timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS },
   ]);
 });
 
@@ -432,7 +432,7 @@ test('openIosApp launches iOS simulator app before opening custom-scheme URL wit
   assert.deepEqual(mockRunCmd.mock.calls[1], [
     'xcrun',
     ['simctl', 'openurl', 'sim-1', 'myapp://item/42'],
-    undefined,
+    { timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS },
   ]);
 });
 
@@ -457,7 +457,7 @@ test('openIosApp launches iOS simulator app before opening https URL with launch
   assert.deepEqual(mockRunCmd.mock.calls[1], [
     'xcrun',
     ['simctl', 'openurl', 'sim-1', 'https://example.com/item/42'],
-    undefined,
+    { timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS },
   ]);
 });
 

packages/platform-apple/src/core/app-launch.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { isIosFamily, isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
-import { execFailureDetails } from '@agent-device/host-kit/command';
+import { isCommandTimeoutError, execFailureDetails } from '@agent-device/host-kit/command';
 import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { ensureHostDirectory, writeHostTextFile } from '@agent-device/host-kit/host-file';
 import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry';
@@ -16,7 +16,11 @@ import {
   isWebUrl,
   resolveIosDeviceDeepLinkBundleId,
 } from '@agent-device/contracts/command';
-import { IOS_APP_LAUNCH_TIMEOUT_MS, IOS_SIMULATOR_TERMINATE_TIMEOUT_MS } from './config.ts';
+import {
+  IOS_APP_LAUNCH_TIMEOUT_MS,
+  IOS_SIMULATOR_OPENURL_TIMEOUT_MS,
+  IOS_SIMULATOR_TERMINATE_TIMEOUT_MS,
+} from './config.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 import { runAppleRunnerCommand } from './runner-client.ts';
 import type { AppleRunnerCommandOptions } from '../runner/index.ts';
@@ -30,12 +34,22 @@ import { ensureBootedSimulator } from './simulator.ts';
 import { runXcrun, type ScopedSimctlCommand } from './tool-provider.ts';
 import { closeMacOsApp, openMacOsApp } from '../os/macos/apps.ts';
 import { resolveIosApp } from './app-resolution.ts';
-import { buildSimctlArgsForDevice, runSimctlForDevice } from './simctl.ts';
+import { buildSimctlArgsForDevice } from './simctl.ts';
 
 const IOS_SIMULATOR_CONSOLE_CAPTURE_MS = 25_000;
 const IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE =
   '--launch-args is not supported with iOS simulator URL opens (simctl openurl ignores launch args). Launch the app first with --launch-args, then issue the URL open in a separate call.';
 
+/** Why an open failed because CoreSimulator never answered its `simctl openurl` within the bound. */
+export const IOS_SIMULATOR_OPENURL_TIMEOUT_REASON = 'ios-simulator-openurl-timeout';
+
+/**
+ * A killed child answers nothing, so the bound cannot report whether the hand-off landed; the hint is
+ * the operator's only notice that a retry can duplicate the deep link.
+ */
+export const IOS_SIMULATOR_OPENURL_TIMEOUT_HINT =
+  'The Simulator may still have received the URL; CoreSimulator is slow to answer. Retry the open, or answer any "Open in" prompt with alert accept.';
+
 // fallow-ignore-next-line complexity
 export async function openIosApp(
   device: DeviceInfo,
@@ -85,7 +99,7 @@ export async function openIosApp(
           await terminateIosSimulatorApp(device, bundleId);
         }
       }
-      await openIosSimulatorUrl(device, explicitUrl, undefined);
+      await openIosSimulatorUrl(device, explicitUrl, undefined, options?.runnerOptions);
       return;
     }
     const appBundleId = options?.appBundleId ?? (await resolveIosApp(device, app));
@@ -110,7 +124,7 @@ export async function openIosApp(
       throw new AppError('INVALID_ARGS', LAUNCH_CONSOLE_DIRECT_APP_ONLY_MESSAGE);
     }
     if (device.kind === 'simulator') {
-      await openIosSimulatorUrl(device, deepLinkTarget, launchArgs);
+      await openIosSimulatorUrl(device, deepLinkTarget, launchArgs, options?.runnerOptions);
       return;
     }
     const bundleId = resolveIosDeviceDeepLinkBundleId(options?.appBundleId, deepLinkTarget);
@@ -148,12 +162,33 @@ async function openIosSimulatorUrl(
   device: DeviceInfo,
   url: string,
   launchArgs: string[] | undefined,
+  runnerOptions?: AppleRunnerCommandOptions,
 ): Promise<void> {
   if (launchArgs && launchArgs.length > 0) {
     throw new AppError('INVALID_ARGS', IOS_SIMULATOR_LAUNCH_ARGS_WITH_URL_MESSAGE);
   }
   await ensureBootedSimulator(device);
-  await runSimctlForDevice(device, ['openurl', device.id, url]);
+  const args = buildSimctlArgsForDevice(device, ['openurl', device.id, url]);
+  try {
+    await runXcrun(args, {
+      timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS,
+      ...(runnerOptions?.signal ? { signal: runnerOptions.signal } : {}),
+    });
+  } catch (error) {
+    // Only a bound this call armed is relabelled; a cancelled request stays a cancelled request.
+    if (!isCommandTimeoutError(error)) throw error;
+    throw new AppError(
+      'COMMAND_FAILED',
+      `xcrun simctl openurl did not answer within ${IOS_SIMULATOR_OPENURL_TIMEOUT_MS}ms.`,
+      {
+        ...error.details,
+        reason: IOS_SIMULATOR_OPENURL_TIMEOUT_REASON,
+        timeoutMs: IOS_SIMULATOR_OPENURL_TIMEOUT_MS,
+        deviceId: device.id,
+        hint: IOS_SIMULATOR_OPENURL_TIMEOUT_HINT,
+      },
+    );
+  }
 }
 
 export async function openIosDevice(device: DeviceInfo): Promise<void> {

packages/platform-apple/src/core/config.ts

@@ -14,6 +14,14 @@ export const IOS_SIMULATOR_FOCUS_TIMEOUT_MS = 10_000;
 
 export const IOS_SIMULATOR_TERMINATE_TIMEOUT_MS = 15_000;
 
+/**
+ * How long a Simulator `simctl openurl` may take. CoreSimulator can hold an URL hand-off for
+ * minutes while it is wedged, and every other simctl call this open makes is bounded; the bound
+ * stays well under the daemon request budget so the open answers with its own typed reason and
+ * kills the child instead of being cancelled around a still-running `openurl`.
+ */
+export const IOS_SIMULATOR_OPENURL_TIMEOUT_MS = 20_000;
+
 export const IOS_SIMULATOR_SCREENSHOT_TIMEOUT_MS = 20_000;
 
 // The CoreDevice panel probe runs on the same request budget as the capture it

packages/platform-apple/src/launch-confirmation.fixtures.ts

@@ -0,0 +1,12 @@
+import { ALERT_NOT_FOUND_RUNNER_CODE } from '@agent-device/contracts/alert-contract';
+import { AppError } from '@agent-device/kernel/errors';
+
+/** The prompt a session app's own launch URL raises. */
+export const CONFIRMATION = { message: 'Open in “Example App”?', items: ['Cancel', 'Open'] };
+
+/** The runner's typed absence: `alert get` looked once and found no alert. */
+export function alertNotFound(): AppError {
+  return new AppError('COMMAND_FAILED', 'alert not found', {
+    runnerErrorCode: ALERT_NOT_FOUND_RUNNER_CODE,
+  });
+}