feat(open): answer the iOS launch confirmation for --launch-url (#3084)

* feat(apple): answer the launch confirmation open --launch-url raises

On an iOS Simulator, `open <bundle> --launch-url <scheme-url>` hands the URL
to SpringBoard, which can hold the launch behind `Open in "<App>"?`. After the
launch settles, the open reads the alert once through the runner. A
confirmation naming the session app (display name from `simctl listapps`) is
accepted, the released launch is observed again, and the outcome carries
`launchConfirmation: 'accepted'`. A confirmation naming any other app is never
accepted: the open fails with `reason: launch_confirmation_foreign_app` and the
named app in `details.appName`. No alert (the runner's typed ALERT_NOT_FOUND)
or a non-confirmation alert leaves the outcome as before. The read is skipped
once the launch budget (IOS_APP_LAUNCH_TIMEOUT_MS) is spent, and a
confirmable open demands the runner even under an observation-only plan.

Tests and the mutation that makes each fail:
- launch-confirmation.test.ts
  - accepts ... curly/straight quotes: drop `"` from the title pattern.
  - foreign app never accepted: replace `namedApp !== sessionAppName` with
    `false`.
  - no alert costs one read: remove the `isAlertNotFoundError` return.
  - non-confirmation alert left for the caller: make the title pattern
    match any `Open in|Allow` prefix.
  - failed alert read reported as itself: catch every read error as absence.
  - port reads/accepts for the session app: drop `appBundleId` from the
    alert target, or return the first listed app's name.
- lifecycle.test.ts
  - accepted and reported: remove the re-settle after accept (event order),
    or keep `resolveAppleSimulatorRunnerDemand` for confirmable opens
    (runnerDemand 'none').
  - no confirmation costs one alert read: same runner-demand mutation.
  - foreign app fails without accepting: skip the foreign-app check.
  - no/web launch URL never reads an alert: drop `!isWebUrl(url)` from
    `confirmable`.
  - physical iOS never reads an alert: drop `device.kind === 'simulator'`
    from `confirmable`.

* feat(open): report launchConfirmation in the open response

`completeOpenCommand` forwards the lifecycle outcome's `launchConfirmation`
into `buildOpenResult`, which sets `data.launchConfirmation` only when the
platform answered a confirmation. The Node client's `apps.open` result carries
it as `launchConfirmation: 'accepted'`. The open command help names both
outcomes.

Tests and the mutation that makes each fail:
- session-open-surface.test.ts "buildOpenResult reports an answered launch
  confirmation...": remove `if (launchConfirmation) result.launchConfirmation`.
- session-open-execution-runtime.test.ts "open reports the launch confirmation
  its platform answered": drop `launchConfirmation: outcome.launchConfirmation`
  from the `buildOpenResult` call.
- client.test.ts "apps.open reports an answered launch confirmation only when
  the daemon answered one": replace `data.launchConfirmation === 'accepted'`
  with `false`.

* docs(commands): describe how open answers the iOS launch confirmation

Adds both outcomes of an iOS Simulator `open --launch-url` prompt to the Navigation notes: a prompt naming the session app is answered and reported as launchConfirmation: "accepted"; a prompt naming another app fails the open with launch_confirmation_foreign_app and details.appName. Docs only; no test.

* test(ios-smoke): delete answerDeepLinkConfirmation now that open answers it

`open --launch-url` answers the `Open in "<App>"?` confirmation itself, so the
smoke lane's `answerDeepLinkConfirmation` / `acceptDeepLinkConfirmationIfPresent`
helper and its unit test are deleted. The three deep-link scenarios (automation
lab, WebView lab, visible-depth frontier) now assert the open either raised no
confirmation or reports `launchConfirmation: "accepted"`, then wait once for
their route landmark with a 30 s budget (the released launch has taken over
20 s to reach the foreground on a loaded CI host). `assertWaitSelector` takes
the same optional `timeoutMs` as `assertWaitText`.

No new unit test: the changed files are live-device scenario code, exercised
only by the iOS Simulator smoke lane. The deleted test covered the deleted
helper.

* feat(cli): print launchConfirmation in open --json output

The CLI serializes open through the Node client result, and serializeOpenResult listed its fields explicitly, so an answered confirmation reached the client but not `open --json`. It now carries `launchConfirmation` when present. Found by the live iOS Simulator run: the runner log showed the confirmation read and accepted while the CLI JSON had no field.

Test and the mutation that makes it fail:
- result-serialization.test.ts "serializeOpenResult carries an answered launch confirmation": delete the launchConfirmation spread in serializeOpenResult.

* fix(apple): read the launch confirmation only when the bridge cannot see the app

The alert read now runs only after the host AX bridge reports the launched
app unobservable, within what is left of the launch budget, so an open whose
app is observed keeps its runner demand and timing. A failed or late read
leaves the open as it was. A prompt is accepted only when its name resolves
to exactly one installed bundle and that bundle is the session app; a name
no single bundle carries is left unanswered, and the foreign-app failure
names foreignAppBundleId and sessionAppBundleId.

* test(client): move apps namespace cases into client-apps.test.ts

client.test.ts grew past the test-file size ratchet (1573 lines vs 1552 at
the merge-base). Move the apps.open and apps.installFromSource cases, which
exercise the client's apps namespace, into their own file. The cases are
moved unchanged.

* fix(apple): read the launch confirmation only when the launched app itself is unreadable

The Simulator launch observation now reports probe-failed, with its typed failure, for an
unresolvable target, an open bridge circuit, or a bridge failure that is not a launch
transition. Only an app with no running process or an expired launch-transition window stays
unobservable, so only those opens read the alert. An open that reads it records runner demand
'required'.

* fix(apple): attribute the launch confirmation to the URL scheme owner within one budget

The sheet title now only recognizes a launch confirmation. The app it would open is the URL
scheme owner from resolveIosSimulatorDeepLinkBundleId, so a localized app name can no longer
attribute a foreign app's sheet to the session app; the listapps name matching is deleted.

The alert read, the runner interactor resolution, the owner lookup and the accept share the
remaining launch budget. A failed or late leg leaves the open as it was, with a diagnostic.

* docs(open): state that open answers only a confirmation present before it sees the app

The --launch-url help and the commands page now attribute the prompt to the URL scheme owner
and say a prompt that appears after open has seen the app is left for alert accept.

* test(ios-smoke): retry the deep-link destination wait in one shared helper

The three deep-link scenarios wait through waitForDeepLinkDestination: up to five 15 s waits,
retried only on a miss that says the destination was not observed yet, with no alert step.
assertLaunchConfirmationAnswered could not fail, so it is deleted.

* refactor(apple): carry the session app with the confirmable launch URL

AppleLaunchPlan.confirmation holds the URL and the bundle it was checked for, so the answer no longer re-checks appBundleId. followUpUrl stays separate: it says how the URL is dispatched, confirmation says whether SpringBoard may hold it, and a direct Simulator launch has both.

* fix(apple): let the confirmation answer finish instead of racing a budget

The race only stopped the waiting: a late accept could still tap the sheet after open returned unanswered. Each step is already bounded (one runner alert get, the simctl owner lookup, actOnAppleAlert's 2 s retry window), so the timer, the Leg enum and the launch-budget arithmetic go away and the answer awaits each step to its own end.

* refactor(apple): read a typed alert absence as no alert at the port

alert.ts maps the backend's typed absence to undefined in alertIfPresent and keeps isAlertNotFoundError private; the answer no longer branches on which step failed.

* refactor(apple): build the confirmation port from one resolved interactor

The port binds readAlert and acceptAlert once; the answer resolves the runner interactor a single time and leaves the open unanswered when it cannot.

* refactor(apple): answer the launch confirmation inside the one open settle

settleAppleOpen observes the launched app as a typed LaunchObservation; when the verdict is unobservable and the plan can answer a confirmation, it answers once and observes again, then writes timing once. The second settle, the delete of a stale failure and the reads back from timing go away, and postOpenSettleDurationMs now spans the whole settle.

* refactor(contracts): give the post-open observation failure one meaning per field

PostOpenObservationFailure is a union keyed by source: capture (Android error code and reason), target (iOS target resolution error code and reason), bridge (bridge failure kind and code), circuit (no fields). The circuit no longer invents a code pair, the bridge no longer swaps kind into code, and the doc note that explained the swap is gone. Android's released fields keep their meaning and gain source.

* fix(apple): report a launch alert open cannot recognize as a confirmation

The runner reports an alert only as its localized title and button labels, and matching the app name is unsafe because permission alerts name the app too, so the confirmation stays recognized by its English title. An alert that is present but not recognized now emits a warn diagnostic with its title and buttons, and commands.md and the open help state the English-only limit.

* fix(apple): bound and abort the launch URL owner lookup

The settle's URL-owner lookup ran simctl listapps and one plutil per
installed app with no timeout and no signal, so a wedged CoreSimulator
held open --launch-url without limit. The lookup now shares one 10 s
deadline across every spawn and the open's signal aborts it.

* test(apple): clear the wedged spawn's timeout when its signal aborts

* test(apple): end a wedged spawn at once when its signal is already aborted

* docs(open): an owner the lookup cannot read is one more unresolved case

* fix(apple): keep the app-list conversion inside the owner lookup budget and surface its timeout

* test(apple): bound the spawn wait and index the last arg with at()

Author: thymikee

packages/contracts/src/application-lifecycle-runtime.ts

@@ -140,8 +140,9 @@ export type OpenApplicationTiming = Readonly<{
  *   or AX-server state that did not clear, a system surface over the app, a content verdict after
  *   the capture's own re-captures, or the window ran out.
  * - `probe-failed`: the observation could not run (Android: the helper is not installed at the
- *   current version, or adb or the accessibility service failed). `postOpenObservationFailure`
- *   carries the typed failure.
+ *   current version, or adb or the accessibility service failed; iOS Simulator: the app's bridge
+ *   target could not be resolved, the bridge circuit is open, or the bridge failed with a code that
+ *   is not a launch transition). `postOpenObservationFailure` carries the typed failure.
  * - `app-unidentified`: the open targeted an app, but the owner could not read which package it
  *   launched, so nothing was observed.
  * - `not-eligible`: the device has no observation path.
@@ -153,15 +154,31 @@ export type PostOpenObservation =
   | 'app-unidentified'
   | 'not-eligible';
 
-/** The typed failure of a `probe-failed` observation: the error code and its typed reason. */
-export type PostOpenObservationFailure = Readonly<{
-  code: string;
-  reason?: string;
-}>;
+/**
+ * The typed failure of a `probe-failed` observation, by what stopped it.
+ * - `capture`: an Android capture failed with this error `code` and typed `reason`.
+ * - `target`: an iOS Simulator could not resolve the app's bridge target; the error `code` and
+ *   typed `reason`.
+ * - `bridge`: the iOS Simulator host AX bridge failed with this failure `kind` and `code`.
+ * - `circuit`: the bridge circuit is open for this app generation, so the probe did not run.
+ */
+export type PostOpenObservationFailure =
+  | Readonly<{ source: 'capture'; code: string; reason?: string }>
+  | Readonly<{ source: 'target'; code: string; reason?: string }>
+  | Readonly<{ source: 'bridge'; kind: string; code: string }>
+  | Readonly<{ source: 'circuit' }>;
+
+/**
+ * A system confirmation the launch itself raised and the open answered. `accepted`: iOS held a
+ * launch URL behind `Open in "<App>"?` naming the session app, and the open accepted it.
+ */
+export type LaunchConfirmation = 'accepted';
 
 export type OpenApplicationOutcome = Readonly<{
   appBundleId?: string;
   timing: OpenApplicationTiming;
+  /** Present only when the open answered a launch confirmation. */
+  launchConfirmation?: LaunchConfirmation;
 }>;
 
 /** Applies or clears a platform's native representation of neutral runtime hints. */

packages/contracts/src/client-app.ts

@@ -1,6 +1,7 @@
 // The public API vocabulary for app install, deploy, open, close and inventory.
 
 import type { AppsFilter } from './app-inventory.ts';
+import type { LaunchConfirmation } from './application-lifecycle-runtime.ts';
 import type { JsonObject } from './json.ts';
 import type { SessionSurface } from './session-surface.ts';
 import type { TargetShutdownResult } from './target-shutdown-contract.ts';
@@ -109,6 +110,11 @@ export type AppOpenResult = {
   runtime?: SessionRuntimeHints;
   selection?: DeviceSelectionMetadata;
   device?: AgentDeviceSessionDevice;
+  /**
+   * `accepted` when iOS held the launch URL behind an `Open in "<App>"?` confirmation naming the
+   * session app and the open answered it.
+   */
+  launchConfirmation?: LaunchConfirmation;
   /**
    * Initial interactive snapshot captured immediately after an open that
    * requested `foreground`, composed from the same snapshot-runtime dispatch

packages/platform-android/src/launch-observation.test.ts

@@ -139,7 +139,7 @@ test('a capture mechanism failure is a failed probe with its typed reason', asyn
 
   await expect(observation.observe()).resolves.toEqual({
     observation: 'probe-failed',
-    failure: { code: 'COMMAND_FAILED', reason: 'accessibility-timeout' },
+    failure: { source: 'capture', code: 'COMMAND_FAILED', reason: 'accessibility-timeout' },
   });
 });
 
@@ -151,7 +151,11 @@ test('a device without the current helper is a failed probe', async () => {
 
   await expect(observation.observe()).resolves.toEqual({
     observation: 'probe-failed',
-    failure: { code: 'COMMAND_FAILED', reason: 'android-snapshot-helper-not-current' },
+    failure: {
+      source: 'capture',
+      code: 'COMMAND_FAILED',
+      reason: 'android-snapshot-helper-not-current',
+    },
   });
 });
 

packages/platform-android/src/launch-observation.ts

@@ -50,5 +50,8 @@ export async function observeAndroidLaunch(
 function typedFailure(error: unknown): PostOpenObservationFailure {
   const normalized = normalizeError(error);
   const reason = readAndroidCaptureFailureReason(normalized) ?? normalized.details?.reason;
-  return typeof reason === 'string' ? { code: normalized.code, reason } : { code: normalized.code };
+  const { code } = normalized;
+  return typeof reason === 'string'
+    ? { source: 'capture', code, reason }
+    : { source: 'capture', code };
 }

packages/platform-android/src/lifecycle.test.ts

@@ -167,6 +167,7 @@ test('a failed launch probe reports its typed failure and the open still succeed
 
   expect(outcome.timing.postOpenObservation).toBe('probe-failed');
   expect(outcome.timing.postOpenObservationFailure).toEqual({
+    source: 'capture',
     code: 'COMMAND_FAILED',
     reason: 'accessibility-timeout',
   });

packages/platform-apple/src/alert.ts

@@ -56,6 +56,16 @@ function runAppleAlert(
     )) as Record<string, unknown>;
 }
 
+/** The alert `read` settles with, or `undefined` when the backend reports a typed absence. */
+export async function alertIfPresent<T>(read: Promise<T>): Promise<T | undefined> {
+  try {
+    return await read;
+  } catch (error) {
+    if (isAlertNotFoundError(error)) return undefined;
+    throw error;
+  }
+}
+
 export async function readAppleAlert(
   device: DeviceInfo,
   runnerOptions: RunnerCallOptions,

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

@@ -2,7 +2,8 @@ import path from 'node:path';
 import { hostFileStat } from '@agent-device/host-kit/host-file';
 import { fileURLToPath } from 'node:url';
 import { isIosFamily, isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
-import { AppError } from '@agent-device/kernel/errors';
+import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
+import { isCommandTimeoutError } from '@agent-device/host-kit/command';
 import type { AppsFilter } from '@agent-device/contracts/device';
 import {
   createAppResolutionCache,
@@ -16,6 +17,7 @@ import { runAppleToolCommand } from './tool-provider.ts';
 import { runSimctlForDevice } from './simctl.ts';
 import { resolveIosPhysicalDeviceControl } from './physical-device-control.ts';
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
+import { Deadline } from '@agent-device/host-kit/retry';
 
 const ALIASES: Record<string, string> = {
   settings: 'com.apple.Preferences',
@@ -168,20 +170,30 @@ type SimulatorAppMetadata = {
   applicationType?: string;
 };
 
+/**
+ * The installed app that owns `url`'s scheme, when exactly one does. `timeoutMs` is one deadline
+ * shared by the app listing and every Info.plist read; a spawn it cuts short or `signal` aborts
+ * rejects the lookup.
+ */
 export async function resolveIosSimulatorDeepLinkBundleId(
   device: DeviceInfo,
   url: string,
+  options: SimulatorAppListOptions = {},
 ): Promise<string | undefined> {
   if (!isIosFamily(device) || device.kind !== 'simulator') return undefined;
   const scheme = parseUrlScheme(url);
   if (!scheme) return undefined;
 
-  const apps = await listSimulatorAppMetadata(device);
+  const remaining = remainingLookupBudget(options);
+  const apps = await listSimulatorAppMetadata(device, remaining());
   const matches: SimulatorAppMetadata[] = [];
   for (const app of apps) {
     if (app.bundleId.startsWith(AGENT_DEVICE_RUNNER_BUNDLE_PREFIX)) continue;
     if (!app.path) continue;
-    const schemes = await readIosSimulatorAppUrlSchemes(path.join(app.path, 'Info.plist'));
+    const schemes = await readIosSimulatorAppUrlSchemes(
+      path.join(app.path, 'Info.plist'),
+      remaining(),
+    );
     if (schemes.has(scheme)) {
       matches.push(app);
     }
@@ -193,6 +205,16 @@ export async function resolveIosSimulatorDeepLinkBundleId(
   return matches.length === 1 ? matches[0]?.bundleId : undefined;
 }
 
+function remainingLookupBudget({
+  timeoutMs,
+  signal,
+}: SimulatorAppListOptions): () => SimulatorAppListOptions {
+  const abortable = signal ? { signal } : {};
+  if (timeoutMs === undefined) return () => abortable;
+  const deadline = Deadline.fromTimeoutMs(timeoutMs);
+  return () => ({ timeoutMs: Math.max(1, deadline.remainingMs()), ...abortable });
+}
+
 function parseUrlScheme(url: string): string | undefined {
   const match = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(url.trim());
   return match?.[1]?.toLowerCase();
@@ -209,10 +231,11 @@ export async function listIosApps(device: DeviceInfo, filter: AppsFilter): Promi
   return await resolveIosPhysicalDeviceControl(device).listApps(device, filter);
 }
 
-type SimulatorAppListOptions = {
+type SimulatorAppListOptions = Readonly<{
   /** Unset (default) preserves prior unbounded behavior for normal command flow. */
   timeoutMs?: number;
-};
+  signal?: AbortSignal;
+}>;
 
 async function listSimulatorApps(
   device: DeviceInfo,
@@ -225,69 +248,31 @@ async function listSimulatorApps(
   }));
 }
 
+type SimulatorAppListRecord = Record<
+  string,
+  {
+    ApplicationType?: string;
+    Bundle?: string;
+    CFBundleDisplayName?: string;
+    CFBundleName?: string;
+    Path?: string;
+  }
+>;
+
 async function listSimulatorAppMetadata(
   device: DeviceInfo,
   options?: SimulatorAppListOptions,
 ): Promise<SimulatorAppMetadata[]> {
+  const remaining = remainingLookupBudget(options ?? {});
   const result = await runSimctlForDevice(device, ['listapps', device.id], {
     allowFailure: true,
-    timeoutMs: options?.timeoutMs,
+    ...remaining(),
   });
-  const stdout = result.stdout as string;
-  const trimmed = stdout.trim();
-  if (!trimmed) return [];
-
-  let parsed: Record<
-    string,
-    {
-      ApplicationType?: string;
-      Bundle?: string;
-      CFBundleDisplayName?: string;
-      CFBundleName?: string;
-      Path?: string;
-    }
-  > | null = null;
-  if (trimmed.startsWith('{')) {
-    try {
-      parsed = JSON.parse(trimmed) as Record<
-        string,
-        {
-          ApplicationType?: string;
-          Bundle?: string;
-          CFBundleDisplayName?: string;
-          CFBundleName?: string;
-          Path?: string;
-        }
-      >;
-    } catch {
-      parsed = null;
-    }
-  }
-
-  if (!parsed && trimmed.startsWith('{')) {
-    try {
-      const converted = await runAppleToolCommand('plutil', ['-convert', 'json', '-o', '-', '-'], {
-        allowFailure: true,
-        stdin: trimmed,
-        timeoutMs: options?.timeoutMs,
-      });
-      if (converted.exitCode === 0 && converted.stdout.trim().startsWith('{')) {
-        parsed = JSON.parse(converted.stdout) as Record<
-          string,
-          {
-            ApplicationType?: string;
-            Bundle?: string;
-            CFBundleDisplayName?: string;
-            CFBundleName?: string;
-            Path?: string;
-          }
-        >;
-      }
-    } catch {
-      parsed = null;
-    }
-  }
+  const trimmed = (result.stdout as string).trim();
+  if (!trimmed.startsWith('{')) return [];
 
+  const parsed =
+    parseSimulatorAppList(trimmed) ?? (await convertSimulatorAppList(trimmed, remaining()));
   if (!parsed) return [];
   return Object.entries(parsed).map(([bundleId, info]) => {
     const appPath = resolveSimulatorAppPath(info);
@@ -300,6 +285,36 @@ async function listSimulatorAppMetadata(
   });
 }
 
+function parseSimulatorAppList(text: string): SimulatorAppListRecord | null {
+  try {
+    return JSON.parse(text) as SimulatorAppListRecord;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `simctl listapps` prints an OpenStep plist on some Xcode versions; `plutil` converts it. A
+ * timeout or abort of that conversion is the lookup's failure, not an empty app list.
+ */
+async function convertSimulatorAppList(
+  text: string,
+  options: SimulatorAppListOptions,
+): Promise<SimulatorAppListRecord | null> {
+  try {
+    const converted = await runAppleToolCommand('plutil', ['-convert', 'json', '-o', '-', '-'], {
+      allowFailure: true,
+      stdin: text,
+      ...options,
+    });
+    if (converted.exitCode !== 0 || !converted.stdout.trim().startsWith('{')) return null;
+    return JSON.parse(converted.stdout) as SimulatorAppListRecord;
+  } catch (error) {
+    if (isCommandTimeoutError(error) || isRequestCanceledError(error)) throw error;
+    return null;
+  }
+}
+
 function resolveSimulatorAppPath(info: { Bundle?: string; Path?: string }): string | undefined {
   if (info.Path) return info.Path;
   if (!info.Bundle) return undefined;
@@ -322,19 +337,22 @@ const iosSimulatorAppUrlSchemeMemo = createTtlMemo<string, Set<string>>({
   scheduleExpiry: true,
 });
 
-async function readIosSimulatorAppUrlSchemes(infoPlistPath: string): Promise<Set<string>> {
+async function readIosSimulatorAppUrlSchemes(
+  infoPlistPath: string,
+  options: SimulatorAppListOptions,
+): Promise<Set<string>> {
   let cacheKey: string | undefined;
   try {
     cacheKey = `${infoPlistPath}:${(await hostFileStat(infoPlistPath)).mtimeMs}`;
   } catch {
     cacheKey = undefined;
   }
   if (cacheKey === undefined) {
-    return (await readIosSimulatorAppUrlSchemesUncached(infoPlistPath)) ?? new Set();
+    return (await readIosSimulatorAppUrlSchemesUncached(infoPlistPath, options)) ?? new Set();
   }
   const cached = iosSimulatorAppUrlSchemeMemo.get(cacheKey);
   if (cached) return cached;
-  const schemes = await readIosSimulatorAppUrlSchemesUncached(infoPlistPath);
+  const schemes = await readIosSimulatorAppUrlSchemesUncached(infoPlistPath, options);
   if (schemes) iosSimulatorAppUrlSchemeMemo.set(cacheKey, schemes);
   return schemes ?? new Set();
 }
@@ -345,13 +363,12 @@ async function readIosSimulatorAppUrlSchemes(infoPlistPath: string): Promise<Set
  */
 async function readIosSimulatorAppUrlSchemesUncached(
   infoPlistPath: string,
+  options: SimulatorAppListOptions,
 ): Promise<Set<string> | undefined> {
   const result = await runAppleToolCommand(
     'plutil',
     ['-convert', 'json', '-o', '-', infoPlistPath],
-    {
-      allowFailure: true,
-    },
+    { allowFailure: true, ...options },
   );
   if (result.exitCode !== 0) return undefined;
   try {