feat(wait): carry the poll evidence on the replay landmark-mismatch refusal

Review follow-up. A replayed selector wait refused for a recorded
landmark mismatch threw without the captures/polls evidence, and when
its final poll ended in a runner restart the refusal hid that outcome.
The refusal now carries the same failure evidence a timeout does, next
to its mismatch details; two regressions cover a mismatch followed by a
deadline-cancelled capture and by a runner restart. Docs and changelog
name the refusal alongside the polling timeout paths.

Author: thymikee

CHANGELOG.md

@@ -6,7 +6,8 @@
   after a readable capture) carry a per-poll timeline in `error.details` (`captures`, `polls[]`
   with `startedMs`, `durationMs`, and a typed `outcome`: readable, unreadable, deadline,
   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
+  opening the request log. Long waits keep the first five and last twenty-five polls. The replay
+  landmark-mismatch refusal carries the same poll evidence next to its mismatch details; `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)

src/commands/interaction/runtime/wait-selector.test.ts

@@ -207,6 +207,98 @@ test('runtime wait fails closed at the deadline when only impostors matched the
   assert.equal(observed.label, 'Screen X');
   const ancestry = error.details?.observedAncestry as Array<{ role: string; label?: string }>;
   assert.equal(ancestry[0]?.label, 'List Screen');
+  assertReadablePollEvidence(error);
+});
+
+/** The refusal carries the same poll evidence a plain timeout would. */
+function assertReadablePollEvidence(error: AppError): void {
+  const details = error.details ?? {};
+  const polls = details.polls as Array<{ outcome: string }>;
+  assert.ok(polls.length >= 1);
+  assert.ok(polls.every((poll) => poll.outcome === 'readable'));
+  assert.equal(details.captures, polls.length);
+  assert.equal(details.readableCaptures, polls.length);
+  assert.equal(typeof details.waitedMs, 'number');
+}
+
+/**
+ * An impostor capture, then a capture that outlives the deadline: the refusal still names the
+ * landmark mismatch, and its poll timeline shows the deadline cutting the last capture short,
+ * with the runner-restart evidence that capture carried.
+ */
+async function landmarkRefusalAfter(
+  finalCapture: () => Promise<ReturnType<typeof landmarkScreen>>,
+): Promise<AppError> {
+  const recorded = recordedLandmarkFor(landmarkScreen('Detail Screen'));
+  let call = 0;
+  const impostor = landmarkScreen('List Screen');
+  const device = createAgentDevice({
+    backend: {
+      platform: 'ios',
+      captureSnapshot: async () => {
+        call += 1;
+        if (call === 1) return { snapshot: impostor };
+        return { snapshot: await finalCapture() };
+      },
+    } satisfies AgentDeviceBackend,
+    artifacts: createLocalArtifactAdapter(),
+    sessions: createMemorySessionStore([{ name: 'default', snapshot: impostor }]),
+    policy: localCommandPolicy(),
+    clock: createFakeClock(100),
+  });
+  const error = await device.selectors
+    .wait({
+      session: 'default',
+      target: {
+        kind: 'selector',
+        selector: 'label="Screen X"',
+        timeoutMs: 400,
+        recordedLandmark: recorded,
+      },
+    })
+    .then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+  assert.ok(error instanceof AppError);
+  assert.equal(error.details?.reason, WAIT_LANDMARK_MISMATCH_REASON);
+  return error;
+}
+
+test('landmark refusal after a deadline-cancelled capture keeps the poll timeline', async () => {
+  const error = await landmarkRefusalAfter(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    return landmarkScreen('List Screen');
+  });
+
+  const polls = error.details?.polls as Array<{ outcome: string }>;
+  assert.deepEqual(
+    polls.map((poll) => poll.outcome),
+    ['readable', 'deadline'],
+  );
+  assert.equal(error.details?.readableCaptures, 1);
+  assert.equal(error.details?.captures, 2);
+});
+
+test('landmark refusal after a runner restart keeps the restart outcome', async () => {
+  const error = await landmarkRefusalAfter(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    throw new AppError('COMMAND_FAILED', 'runner restarted', {
+      runnerRestarted: true,
+      runnerRestartReason: 'runner_readiness_preflight_failed_before_command_send',
+    });
+  });
+
+  const polls = error.details?.polls as Array<{ outcome: string }>;
+  assert.deepEqual(
+    polls.map((poll) => poll.outcome),
+    ['readable', 'runner-restart'],
+  );
+  assert.equal(error.details?.runnerRestarted, true);
+  assert.equal(
+    error.details?.runnerRestartReason,
+    'runner_readiness_preflight_failed_before_command_send',
+  );
 });
 
 test('runtime wait with a recorded landmark keeps the plain timeout when the selector never matched', async () => {

src/commands/interaction/runtime/wait-selector.ts

@@ -119,10 +119,12 @@ export async function waitForSelector<Runtime extends SelectorWaitRuntime>(
     await polling.sleepUntilNextPoll();
   }
   if (deadline !== 'capture-stalled' && landmarkMismatch) {
+    // The refusal keeps the poll evidence a plain timeout would carry, including a runner
+    // restart on the final poll: the mismatch is the verdict, not the whole story of the wait.
     throw new AppError(
       'COMMAND_FAILED',
       `wait matched selector ${selectorExpression} but no candidate carried the recorded landmark identity`,
-      { reason: WAIT_LANDMARK_MISMATCH_REASON, ...landmarkMismatch },
+      { reason: WAIT_LANDMARK_MISMATCH_REASON, ...polling.failureEvidence(), ...landmarkMismatch },
     );
   }
   throw waitTimeoutError(`wait timed out for selector: ${selectorExpression}`, polling, deadline);

website/docs/docs/commands.md

@@ -419,7 +419,7 @@ agent-device alert dismiss
 - Because `wait @ref` is text-based after resolution, duplicate labels can match a different element than the original ref target.
 - `wait` shares the selector/snapshot resolution flow used by `click`, `fill`, `get`, and `is`.
 - Wait failures carry a structured `error.details.reason` in `--json` output: `wait_target_absent` proves a positive wait never found a match; `wait_target_present` means strict `wait absent` reached its deadline with valid captures that still contained matches; `predicate_failed` means strict `wait absent` could not prove absence because no valid capture arrived, with the final observation/diagnostic preserved; `wait_capture_stalled` means no readable capture arrived and is retriable; `wait_deadline_exceeded` means a later capture consumed the remaining budget after an earlier readable capture; `wait_landmark_identity_mismatch` is a replay destination-guard refusal; and `wait_stable_timeout` means the UI did not settle. Use `readableCaptures`, `waitedMs`, `matches`, and `firstMatch` instead of parsing error text. `firstMatch` carries identity/text evidence only; absence failures do not claim visibility or rect evidence.
-- Polling wait timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent` once a readable capture has been seen) also carry `captures` (every poll attempted), `readableCaptures`, and `polls`, one entry per poll with `startedMs` on the wait's own clock, `durationMs`, and `outcome` (`readable`, `unreadable`, `deadline`, or `runner-restart`), so a timeout says where its budget went; long waits keep the first five and last twenty-five polls. `wait --stable` timeouts and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log.
+- Polling wait timeouts (`wait <selector>`, `wait text`, `wait @ref`, and `wait absent` once a readable capture has been seen) also carry `captures` (every poll attempted), `readableCaptures`, and `polls`, one entry per poll with `startedMs` on the wait's own clock, `durationMs`, and `outcome` (`readable`, `unreadable`, `deadline`, or `runner-restart`), so a timeout says where its budget went; long waits keep the first five and last twenty-five polls. A replayed selector wait refused for a recorded landmark mismatch (`wait_landmark_identity_mismatch`) carries the same poll evidence next to its mismatch details. `wait --stable` timeouts and a never-readable strict absence keep their own diagnostics. `logPath` links the full request log.
 - `alert` inspects or handles system alerts on iOS simulator, macOS desktop, and Android native/runtime permission dialogs.
 - `alert` without an action is equivalent to `alert get`.
 - `accept` and `dismiss` are sent once on every platform. A lost or unconfirmed response is reported as an error and never replayed; run `alert get` before acting again.