fix(apple): type the alert-absence retry instead of matching error prose

Review blocker 1 on #2021. The Apple alert legs decided retry and hint
eligibility by substring-matching error messages for "alert not found" / "no
alert", and `alert wait` swallowed *every* read failure. A dead runner, an
unreachable macOS helper or a canceled request was therefore spent as poll
budget and finally reported as `alert wait timed out`, hiding the real cause.

Both backends now state absence as typed evidence:

- The XCTest runner answers `ErrorPayload(code: "ALERT_NOT_FOUND", ...)`. It is
  diagnostic-only, so it stays `COMMAND_FAILED` on the wire and surfaces as
  `details.runnerErrorCode` — the same shape `RUNNER_BUSY` already used.
- The macOS helper adds `reason: "alert-not-found"` to its JSON error details,
  which the helper client already forwards verbatim.

`isAlertNotFoundError` reads only those two fields. `awaitAppleAlert` re-throws
anything that is not a typed absence instead of polling through it, and the
scoped-snapshot fallback hint attaches to typed absence alone.

The three tests the review asked for, plus coverage the daemon-altitude copies
could not express: a non-absence failure propagates immediately from `wait`; an
action does not retry a failure whose message merely reads like an absence; the
macOS helper's typed reason is retried like the runner's. The daemon-level
non-absence test moved to the family suite that owns this policy since R59,
lowering that file's size pin.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019RpfS12XApXqasuAWZJaEX

Author: claude

apple/macos-helper/Sources/AgentDeviceMacOSHelper/main.swift

@@ -287,9 +287,14 @@ struct AgentDeviceMacOSHelper {
     let surface = optionValue(arguments: Array(arguments.dropFirst()), name: "--surface")
     let app = try resolveTargetApplication(bundleId: bundleId, surface: surface)
     guard let alertElement = findAlertElement(appElement: AXUIElementCreateApplication(app.processIdentifier)) else {
+      // `reason` is the typed channel the host retries on; the message is for humans only.
       throw HelperError.commandFailed(
         "alert not found",
-        details: ["bundleId": app.bundleIdentifier ?? "", "appName": app.localizedName ?? ""]
+        details: [
+          "reason": "alert-not-found",
+          "bundleId": app.bundleIdentifier ?? "",
+          "appName": app.localizedName ?? "",
+        ]
       )
     }
     let buttons = collectButtons(root: alertElement)

apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -2190,7 +2190,12 @@ extension RunnerTests {
         Self.alertCommandTimeout(timeoutMs: command.timeoutMs)
       )
       guard let alert = resolveAlert(app: activeApp, deadline: deadline) else {
-        return Response(ok: false, error: ErrorPayload(message: "alert not found"))
+        // Typed so the host retries on absence alone: a transport or runner failure carries no
+        // code and must not be mistaken for "no alert yet" (ALERT_NOT_FOUND_RUNNER_CODE).
+        return Response(
+          ok: false,
+          error: ErrorPayload(code: "ALERT_NOT_FOUND", message: "alert not found")
+        )
       }
       return handleAlert(alert, action: action, deadline: deadline)
     case .gesture:

packages/contracts/src/alert-contract.ts

@@ -2,6 +2,16 @@ export const ALERT_POLL_INTERVAL_MS = 300;
 export const DEFAULT_ALERT_TIMEOUT_MS = 10_000;
 export const ALERT_ACTION_RETRY_MS = 2_000;
 
+/**
+ * The one alert failure the family retries on: the backend looked and there was no alert *yet*.
+ * Both Apple backends state it in typed form — the XCTest runner as this `ErrorPayload.code`
+ * (surfacing as `details.runnerErrorCode`, like `RUNNER_BUSY`, without changing the wire error
+ * code), the macOS helper as `details.reason`. Retry and the fallback hint key on these, never on
+ * the message text: a transport, runner or helper failure must never read as an absent alert.
+ */
+export const ALERT_NOT_FOUND_RUNNER_CODE = 'ALERT_NOT_FOUND';
+export const ALERT_NOT_FOUND_REASON = 'alert-not-found';
+
 export const ALERT_ACTIONS = ['get', 'accept', 'dismiss', 'wait'] as const;
 export type AlertAction = (typeof ALERT_ACTIONS)[number];
 

packages/contracts/src/facades/interaction.ts

@@ -1,6 +1,8 @@
 export {
   ALERT_ACTIONS,
   ALERT_ACTION_RETRY_MS,
+  ALERT_NOT_FOUND_REASON,
+  ALERT_NOT_FOUND_RUNNER_CODE,
   ALERT_POLL_INTERVAL_MS,
   DEFAULT_ALERT_TIMEOUT_MS,
 } from '../alert-contract.ts';

scripts/__tests__/test-file-size-ratchet.test.ts

@@ -34,7 +34,7 @@ const TRIPWIRE_LINES = 1_000;
 // Exact current lengths. Lower a pin when its file shrinks; never raise one — extract instead.
 const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'src/__tests__/remote-connection.test.ts': 2973,
-  'src/daemon/handlers/__tests__/snapshot-handler.test.ts': 2301,
+  'src/daemon/handlers/__tests__/snapshot-handler.test.ts': 2284,
   'src/commands/interaction/runtime/settle.test.ts': 2359,
   'src/daemon/handlers/__tests__/session-replay-runtime-maestro.test.ts': 2020,
   'src/platforms/apple/core/__tests__/runner-session.test.ts': 2001,

src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -2134,15 +2134,23 @@ test('wait selector bypasses a fresh matching session snapshot', async () => {
   );
 });
 
-test('alert accept retries on "alert not found" and succeeds on second attempt', async () => {
+/**
+ * Absence as the XCTest runner states it (`ALERT_NOT_FOUND` surfaces as `details.runnerErrorCode`).
+ * The retry and the fallback hint key on that evidence, never on the message text.
+ */
+function alertAbsence(message = 'alert not found'): AppError {
+  return new AppError('COMMAND_FAILED', message, { runnerErrorCode: 'ALERT_NOT_FOUND' });
+}
+
+test('alert accept retries a typed alert absence and succeeds on the second attempt', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
   sessionStore.set(sessionName, makeSession(sessionName, iosSimulatorDevice));
 
   let calls = 0;
   mockRunnerCommand.mockImplementation(async () => {
     calls += 1;
-    if (calls === 1) throw new AppError('COMMAND_FAILED', 'alert not found');
+    if (calls === 1) throw alertAbsence();
     return { accepted: true };
   });
 
@@ -2163,41 +2171,16 @@ test('alert accept retries on "alert not found" and succeeds on second attempt',
   });
 });
 
-test('alert accept does not retry on non-alert errors', async () => {
-  const sessionStore = makeSessionStore();
-  const sessionName = 'ios-sim';
-  sessionStore.set(sessionName, makeSession(sessionName, iosSimulatorDevice));
-
-  let calls = 0;
-  mockRunnerCommand.mockImplementation(async () => {
-    calls += 1;
-    throw new AppError('COMMAND_FAILED', 'runner crashed');
-  });
-
-  await expect(
-    handleSnapshotCommands({
-      req: {
-        token: 't',
-        session: sessionName,
-        command: 'alert',
-        positionals: ['accept'],
-        flags: {},
-      },
-      sessionName,
-      logPath: '/tmp/daemon.log',
-      sessionStore,
-    }),
-  ).rejects.toThrow('runner crashed');
-
-  expect(calls).toBe(1);
-});
+// The non-absence case moved to `src/platforms/apple/__tests__/alert.test.ts` with the retry policy
+// itself (R59), where it also covers a failure whose message merely reads like an absence — the
+// case this daemon-altitude copy could not distinguish.
 
 test('alert accept adds a scoped-snapshot hint after retrying alert-not-found failures', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
   sessionStore.set(sessionName, makeSession(sessionName, iosSimulatorDevice));
 
-  mockRunnerCommand.mockRejectedValue(new AppError('COMMAND_FAILED', 'alert not found'));
+  mockRunnerCommand.mockRejectedValue(alertAbsence());
 
   let thrown: unknown;
   try {
@@ -2222,15 +2205,15 @@ test('alert accept adds a scoped-snapshot hint after retrying alert-not-found fa
   expect((thrown as AppError).details?.hint).toMatch(/scoped snapshot/i);
 });
 
-test('alert dismiss retries on "no alert" message', async () => {
+test('alert dismiss retries a typed absence whatever the message says', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
   sessionStore.set(sessionName, makeSession(sessionName, iosSimulatorDevice));
 
   let calls = 0;
   mockRunnerCommand.mockImplementation(async () => {
     calls += 1;
-    if (calls < 3) throw new AppError('COMMAND_FAILED', 'no alert present');
+    if (calls < 3) throw alertAbsence('no alert present');
     return { dismissed: true };
   });
 

src/platforms/apple/__tests__/alert.test.ts

@@ -4,6 +4,10 @@ import { afterEach, test, vi } from 'vitest';
 vi.mock('../core/runner/runner-client.ts', () => ({ runAppleRunnerCommand: vi.fn() }));
 vi.mock('../os/macos/helper.ts', () => ({ runMacOsAlertAction: vi.fn() }));
 
+import {
+  ALERT_NOT_FOUND_REASON,
+  ALERT_NOT_FOUND_RUNNER_CODE,
+} from '@agent-device/contracts/alert-contract';
 import { AppError } from '@agent-device/kernel/errors';
 import { IOS_SIMULATOR, MACOS_DEVICE } from '../../../__tests__/test-utils/device-fixtures.ts';
 import { runAppleRunnerCommand } from '../core/runner/runner-client.ts';
@@ -14,6 +18,20 @@ const mockRunner = vi.mocked(runAppleRunnerCommand);
 const mockHelper = vi.mocked(runMacOsAlertAction);
 const runnerOptions = {};
 
+/**
+ * Absence as each backend states it. The message is deliberately the same prose the old predicate
+ * matched on, so a test that passes here is passing on the typed evidence and nothing else.
+ */
+function runnerAbsence(): AppError {
+  return new AppError('COMMAND_FAILED', 'alert not found', {
+    runnerErrorCode: ALERT_NOT_FOUND_RUNNER_CODE,
+  });
+}
+
+function helperAbsence(): AppError {
+  return new AppError('COMMAND_FAILED', 'alert not found', { reason: ALERT_NOT_FOUND_REASON });
+}
+
 afterEach(() => {
   vi.useRealTimers();
   mockRunner.mockReset();
@@ -40,7 +58,7 @@ test('a wait polls until one attempt answers, and the first attempt gets the who
   let calls = 0;
   mockRunner.mockImplementation(async () => {
     calls += 1;
-    if (calls === 1) throw new AppError('COMMAND_FAILED', 'alert not found');
+    if (calls === 1) throw runnerAbsence();
     return { title: 'Camera Access' };
   });
 
@@ -56,7 +74,7 @@ test('a wait polls until one attempt answers, and the first attempt gets the who
 
 test('a wait that never sees an alert reports the timeout rather than the last attempt error', async () => {
   vi.useFakeTimers();
-  mockRunner.mockRejectedValue(new AppError('COMMAND_FAILED', 'alert not found'));
+  mockRunner.mockRejectedValue(runnerAbsence());
 
   const outcome = awaitAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 900 }).then(
     () => undefined,
@@ -87,7 +105,7 @@ test('an accept retries only while the backend says the alert is not there yet',
 
 test('an exhausted accept carries the scoped-snapshot fallback the agent needs next', async () => {
   vi.useFakeTimers();
-  mockRunner.mockRejectedValue(new AppError('COMMAND_FAILED', 'alert not found'));
+  mockRunner.mockRejectedValue(runnerAbsence());
 
   const outcome = actOnAppleAlert(IOS_SIMULATOR, runnerOptions, 'accept').then(
     () => undefined,
@@ -100,6 +118,67 @@ test('an exhausted accept carries the scoped-snapshot fallback the agent needs n
   assert.match(String(error.details?.hint), /scoped snapshot/i);
 });
 
+// The whole point of typing absence: a backend that failed for any other reason must not be
+// retried until the window expires and then reported as a timeout. These three pin that the
+// evidence — not the message text — is what decides.
+test('a wait propagates a non-absence failure instead of spending it as poll budget', async () => {
+  vi.useFakeTimers();
+  let calls = 0;
+  // The message deliberately says "alert not found"; only the missing typed evidence matters.
+  mockRunner.mockImplementation(async () => {
+    calls += 1;
+    throw new AppError('COMMAND_FAILED', 'runner transport closed: alert not found');
+  });
+
+  const outcome = awaitAppleAlert(IOS_SIMULATOR, runnerOptions, { timeoutMs: 5_000 }).then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(6_000);
+
+  assert.match(String(((await outcome) as Error).message), /runner transport closed/);
+  assert.equal(calls, 1);
+});
+
+test('an action does not retry a failure that only reads like an absence', async () => {
+  vi.useFakeTimers();
+  let calls = 0;
+  mockRunner.mockImplementation(async () => {
+    calls += 1;
+    throw new AppError('COMMAND_FAILED', 'no alert service on this runner');
+  });
+
+  const outcome = actOnAppleAlert(IOS_SIMULATOR, runnerOptions, 'dismiss').then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(3_500);
+  const error = (await outcome) as AppError;
+
+  assert.equal(calls, 1);
+  // The fallback hint is absence-only advice, so an untyped failure must not carry it either.
+  assert.equal(error.details?.hint, undefined);
+});
+
+test('the macOS helper states absence as a typed reason, and the family retries it', async () => {
+  vi.useFakeTimers();
+  let calls = 0;
+  mockHelper.mockImplementation(async () => {
+    calls += 1;
+    throw helperAbsence();
+  });
+
+  const outcome = actOnAppleAlert(MACOS_DEVICE, runnerOptions, 'accept').then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  await vi.advanceTimersByTimeAsync(3_500);
+  const error = (await outcome) as AppError;
+
+  assert.ok(calls > 1, 'a typed absence is retried');
+  assert.match(String(error.details?.hint), /scoped snapshot/i);
+});
+
 // The macOS host answers through its helper, and a frontmost-app session names no bundle at all.
 test('the macOS host reads through its helper, and a frontmost-app session names no bundle', async () => {
   mockHelper.mockResolvedValue({ title: 'Allow access' });

src/platforms/apple/alert.ts

@@ -1,5 +1,7 @@
 import {
   ALERT_ACTION_RETRY_MS,
+  ALERT_NOT_FOUND_REASON,
+  ALERT_NOT_FOUND_RUNNER_CODE,
   ALERT_POLL_INTERVAL_MS,
   DEFAULT_ALERT_TIMEOUT_MS,
 } from '@agent-device/contracts/alert-contract';
@@ -15,9 +17,14 @@ import { runMacOsAlertAction } from './os/macos/helper.ts';
 
 /**
  * Apple's four alert legs. R59 moved them here from the daemon: how long to look for a transient
- * alert, how many times to re-ask a runner that answers "alert not found", and which of the two
- * Apple backends answers at all are family mechanics, not request policy. What the caller supplies
- * is the window it allows and the session's target; everything else is this family's.
+ * alert, how many times to re-ask a backend that reports the alert is not there yet, and which of
+ * the two Apple backends answers at all are family mechanics, not request policy. What the caller
+ * supplies is the window it allows and the session's target; everything else is this family's.
+ *
+ * Absence is the one retriable outcome, and both backends state it as typed evidence — the XCTest
+ * runner as `ALERT_NOT_FOUND`, the macOS helper as `reason: 'alert-not-found'`. Nothing here reads
+ * an error message: a transport, runner or helper failure that happened to mention an alert would
+ * otherwise be retried until the window expired and then reported as a timeout, hiding the cause.
  */
 type NativeAlertAction = 'get' | 'accept' | 'dismiss';
 
@@ -75,18 +82,21 @@ export async function awaitAppleAlert(
       const budgetMs = firstAttempt ? timeout : remainingBudgetMs(start, timeout);
       firstAttempt = false;
       return await runAlert('get', budgetMs);
-    } catch {
-      // keep waiting
+    } catch (error) {
+      // Only a typed absence is worth waiting out. Anything else — a dead runner, an unreachable
+      // helper, a canceled request — is reported as itself rather than spent as poll budget and
+      // relabeled `alert wait timed out`.
+      if (!isAlertNotFoundError(error)) throw error;
     }
     await sleep(ALERT_POLL_INTERVAL_MS);
   }
   throw new AppError('COMMAND_FAILED', 'alert wait timed out');
 }
 
 /**
- * Accept and dismiss retry only while the backend keeps saying the alert is not there yet — a
- * sheet that is still animating in. Any other failure is reported on its first occurrence, and
- * an exhausted retry window carries the scoped-snapshot fallback the agent needs next.
+ * Accept and dismiss retry only while the backend keeps reporting a typed absence — a sheet that
+ * is still animating in. Any other failure is reported on its first occurrence, and an exhausted
+ * retry window carries the scoped-snapshot fallback the agent needs next.
  */
 export async function actOnAppleAlert(
   device: DeviceInfo,
@@ -127,7 +137,16 @@ function withAlertFallbackHint(error: unknown): unknown {
   });
 }
 
+/**
+ * Absence, as the backend itself classified it. The XCTest runner's `ALERT_NOT_FOUND` arrives as
+ * `details.runnerErrorCode` (it stays `COMMAND_FAILED` on the wire, like `RUNNER_BUSY`); the macOS
+ * helper's arrives as `details.reason`, forwarded verbatim from its JSON error envelope.
+ */
 function isAlertNotFoundError(error: unknown): boolean {
-  const message = String((error as { message?: unknown })?.message ?? '').toLowerCase();
-  return message.includes('alert not found') || message.includes('no alert');
+  if (!(error instanceof AppError)) return false;
+  const details = error.details ?? {};
+  return (
+    details['runnerErrorCode'] === ALERT_NOT_FOUND_RUNNER_CODE ||
+    details['reason'] === ALERT_NOT_FOUND_REASON
+  );
 }

src/platforms/apple/core/runner/runner-session.ts

@@ -1,4 +1,5 @@
 import { AppError, toAppErrorCode, createRequestCanceledError } from '@agent-device/kernel/errors';
+import { ALERT_NOT_FOUND_RUNNER_CODE } from '@agent-device/contracts/alert-contract';
 import { type ExecResult } from '../../../../utils/exec.ts';
 import { withKeyedLock } from '../../../../utils/keyed-lock.ts';
 import { Deadline } from '../../../../utils/retry.ts';
@@ -891,8 +892,20 @@ function readRunnerErrorCode(rawCode: unknown): string | undefined {
   return typeof rawCode === 'string' && rawCode.trim().length > 0 ? rawCode.trim() : undefined;
 }
 
+/**
+ * Runner codes that classify a failure for the host without renaming it on the wire. They stay
+ * `COMMAND_FAILED` and survive as `details.runnerErrorCode`, which is what family policy reads:
+ * `RUNNER_BUSY` for retriable contention, `ALERT_NOT_FOUND` for an alert that is not there yet.
+ */
+const DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES: ReadonlySet<string> = new Set([
+  'RUNNER_BUSY',
+  ALERT_NOT_FOUND_RUNNER_CODE,
+]);
+
 function runnerAppErrorCode(runnerErrorCode: string | undefined): AppError['code'] {
-  if (runnerErrorCode === 'RUNNER_BUSY') return 'COMMAND_FAILED';
+  if (runnerErrorCode !== undefined && DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES.has(runnerErrorCode)) {
+    return 'COMMAND_FAILED';
+  }
   return runnerErrorCode ? toAppErrorCode(runnerErrorCode) : 'COMMAND_FAILED';
 }