simframe 0.10.0 → 0.11.0

package/src/actions.js

@@ -6,6 +6,12 @@ import * as api from './index.js';
 import * as graph from './graph.js';
 import * as input from './input.js';
 import * as intent from './intent.js';
+import * as matching from './matching.js';
+import * as vocabulary from './vocabulary.js';
+import * as wrote from './wrote.js';
+import * as supervisor from './supervisor.js';
+import * as view from './view.js';
+import * as planner from './planner.js';
 import * as metrics from './metrics.js';
 import * as screenmap from './screenmap.js';
 import { launchApp, openUrl, setPermission, terminateApp } from './platform/index.js';
@@ -35,6 +41,19 @@ const MAX_PAUSE_MS = 5000;
  * transitions that never happened. See docs/BENCHMARKS.md, Phase 11.
  */
 const FOCUS_STABLE_MS = 250;
+/** How far a control's centre may move between the read and the readback. */
+const FIELD_READBACK_RADIUS = 40;
+// The OCR pass needs a far wider one, and 40 is why measuring mattered: OCR
+// reports a value at the *value's* centre, not the label's tap point, and on a
+// pinch-zoomed page those were 133pt apart on a field that had filled
+// correctly. Generous enough for that, still short of "anywhere on screen",
+// because a match found anywhere would happily confirm text that was already
+// there before the step ran.
+const FIELD_READBACK_OCR_RADIUS = 220;
+// How long the OCR readback waits for a frame that postdates the keystrokes.
+// Focusing a web input makes Safari re-zoom, so the settle here is doing real
+// work rather than padding.
+const READBACK_SETTLE_MS = 900;
 /**
  * The cold defaults, unchanged, for a field this screen has not been measured
  * focusing. `graph.focusPlan` takes over once it has been, and may only make
@@ -46,6 +65,16 @@ const FOCUS_STABLE_MS = 250;
  */
 const FOCUS_REACTION_MS = 900;
 const FOCUS_TIMEOUT_MS = 3000;
+
+/**
+ * The settle budget for an action that is not supposed to navigate.
+ *
+ * A change-based settle cannot be satisfied by an action that changes nothing,
+ * so the only question is how long to spend finding that out. Long enough for
+ * keystrokes to land and no longer.
+ */
+const STAYS_PUT_STILLNESS_MS = 200;
+const STAYS_PUT_BUDGET_MS = 600;
 const POLL_MS = 250;
 /** A list that has not produced the target in this many screens does not contain it. */
 const MAX_SCROLLS = 20;
@@ -57,7 +86,7 @@ const MAX_SCROLLS = 20;
  * permission can change what the app shows.
  */
 const ACTION_STEPS = new Set([
-  'tap', 'tapAt', 'type', 'paste', 'swipe', 'scroll', 'scrollTo', 'button', 'key',
+  'tap', 'tapAt', 'type', 'paste', 'clear', 'swipe', 'scroll', 'scrollTo', 'button', 'key',
   'launch', 'terminate', 'openUrl', 'confirm', 'chooseAny', 'permission',
 ]);
 
@@ -90,6 +119,16 @@ export function wrongTurnFrom(verification) {
   return verification?.verdict === 'unexpected-screen';
 }
 
+/**
+ * What a step was asked to act on, in the caller's words.
+ *
+ * Every escalation wants this and two sites were spelling it out separately —
+ * one of them not at all.
+ */
+export function goalOf(step = {}) {
+  return step.value ?? step.target ?? step.label ?? step.into ?? null;
+}
+
 /**
  * What a halted step does to the run as a whole.
  *
@@ -131,6 +170,19 @@ export async function runScript(
     // compared against a human baseline.
     flowName = null,
     minSteps = null,
+    // What the plan wants its supervisor to know.
+    //
+    // The owner's insight, and it is what made the supervisor usable. Asked
+    // cold, it called a list that was plainly still arriving a dead end —
+    // because it does not know this app and Claude, by the time it writes the
+    // plan, does. So the plan briefs its own first responder: `supervise` is
+    // the batch's standing guidance, and a step may add `expect` of its own.
+    //
+    // It is also the correction channel. When the supervisor stops a run, the
+    // result says so, names the remaining steps, and tells the caller that
+    // re-issuing them with a `supervise` note will not stop again for that
+    // reason. A wrong local decision costs one message, not a re-plan.
+    supervise = null,
     options,
   } = {},
 ) {
@@ -143,6 +195,7 @@ export async function runScript(
   const flowId = metrics.newFlowId();
   const escalations = [];
   const verdicts = [];
+  const supervisions = [];
   // Named noteEscalation, not note: the step loop below declares its own
   // `note` string for the no-visible-change suffix, which shadowed this and
   // turned every escalating verdict into a failed step reading "note is not a
@@ -204,6 +257,8 @@ export async function runScript(
     }
   };
 
+  let consecutiveFailures = 0;
+  let lastFailureScreen = null;
   for (const [i, raw] of steps.entries()) {
     const step = normalizeStep(raw);
     const stepStart = Date.now();
@@ -243,7 +298,105 @@ export async function runScript(
         }),
         observedMs: null,
       };
-      let detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+      let detail;
+      // A selector that did not resolve gets the step's own alternatives before
+      // the batch is abandoned. Anything else propagates: retrying from a screen
+      // we did not expect to be on is not a retry, it is a second guess.
+      try {
+        detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+      } catch (thrown) {
+        let err = thrown;
+        // Ask the supervisor before anything is abandoned. It sits behind the
+        // hands and in front of the reasoner: first responder, not
+        // decision-maker, and its whole vocabulary is wait/retry/stop.
+        const ruling = await superviseFailure(deviceQuery, {
+          goal: supervise ?? flowName, step, expected: step.expect, err, options,
+        });
+        if (ruling?.decision === 'wait' || ruling?.decision === 'retry') {
+          // Both wait and retry settle first, differing only in how long.
+          //
+          // The one distinction the model still fumbles is wait against retry —
+          // it called a loading list `retry` on the bench, which without a
+          // settle would fail again immediately for the same reason. Making the
+          // difference a duration rather than a behaviour means a wrong choice
+          // between them costs milliseconds instead of the recovery. The
+          // decision that actually matters is stop against continue, and on
+          // that it has been right every time it was asked something code could
+          // not already answer.
+          await api.waitFor(deviceQuery, {
+            mode: 'settle',
+            stableMs: 400,
+            timeoutMs: ruling.decision === 'wait' ? SUPERVISOR_WAIT_MS : SUPERVISOR_RETRY_MS,
+            options,
+          }).catch(() => null);
+          try {
+            detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+            detail += ` [the local supervisor said ${ruling.decision}; it worked on the second attempt]`;
+            supervisions.push({ index: i, decision: ruling.decision, reason: ruling.reason, outcome: 'recovered' });
+            continue;
+          } catch (again) {
+            supervisions.push({ index: i, decision: ruling.decision, reason: ruling.reason, outcome: 'still failed' });
+            err = again;
+          }
+        } else if (!ruling && supervisor.requested(options)) {
+          // Attempted and got nothing. This was invisible for a whole round:
+          // three rulings, then twenty supervised calls and six failures with
+          // no output at all, while `doctor` in a separate process reported the
+          // model healthy. The reporter's own words — *"had I run flow 2 alone
+          // I would have reported the supervisor makes no difference without
+          // realising it had never run"*.
+          supervisions.push({ index: i, decision: 'unavailable', reason: 'the supervisor did not answer', outcome: 'no ruling' });
+          err.message += ' — the local supervisor was consulted and did not answer, so this failure was not judged.';
+        } else if (ruling?.decision === 'stop') {
+          supervisions.push({ index: i, decision: 'stop', reason: ruling.reason, from: ruling.from, outcome: 'stopped the run' });
+          const remaining = steps.slice(i);
+          err.message += ` — the local supervisor stopped the run here.`
+            + ` ${remaining.length} step(s) were not attempted.`
+            + ' If that judgement was wrong, re-issue the remaining steps with a `supervise` note'
+            + ' telling it what to expect, and it will not stop for this reason again.';
+          err.remainingSteps = remaining;
+        }
+        const { allowed, refused } = permittedAlternatives(step);
+        if (!allowed.length || !mayRetryAfter(err)) {
+          if (refused.length) {
+            err.message += ` (${refused.length} alternative(s) refused locally: `
+              + `${refused.map((r) => `"${r.label}" — ${r.reason}`).join('; ')})`;
+          }
+          throw err;
+        }
+        const tried = [step.value ?? step.target ?? step.label ?? step.into];
+        let last = err;
+        for (const label of allowed) {
+          try {
+            detail = await runStep(deviceQuery, udid, stepWithTarget(step, label), { screen, options, frames, focus });
+            detail += ` [after ${tried.map((t) => JSON.stringify(String(t))).join(', ')} did not resolve]`;
+            last = null;
+            break;
+          } catch (again) {
+            tried.push(label);
+            last = again;
+            if (!mayRetryAfter(again)) break;
+          }
+        }
+        if (last) {
+          // When every selector misses and the screen moved a moment ago, the
+          // problem is timing and not naming. Reported: three fallbacks all
+          // failed because an asset list had not arrived, and the three-label
+          // failure message read like a naming problem and pointed away from
+          // the cause. The reporter's summary — *"fallbacks are a cure for 'I
+          // named it wrong'; almost everything that actually failed failed
+          // because 'it is not there yet'"* — is the finding, and the least a
+          // failure can do is not mislead about which of the two it was.
+          const churning = await recentlyChanged(deviceQuery, options);
+          last.message = `none of ${tried.length} selector(s) resolved `
+            + `(${tried.map((t) => JSON.stringify(String(t))).join(', ')}).`
+            + (churning
+              ? ` The screen has only been still for ${churning}ms, so this is very likely timing rather than naming:`
+                + ' waitFor a string from the loaded state instead of adding more labels.'
+              : ` Last: ${last.message}`);
+          throw last;
+        }
+      }
       // How long this screen must hold still before it counts as settled.
       //
       // 500 ms was a constant paid by every step of every flow, and it is the
@@ -287,11 +440,24 @@ export async function runScript(
         ?? (learned && !learned.cold ? Math.max(learned.timeoutMs, floorMs) : timeoutMs);
       const settleFor = async () => {
         if (!autoSettle || !ACTION_STEPS.has(step.action)) return null;
+        // An action whose correct outcome is that the screen stays put cannot
+        // satisfy a change-based settle, so it pays the whole budget and then
+        // reports failure. Measured on a still screen: 1.9-2.0 seconds burned,
+        // `satisfied: false`, `sawChange: false`. Typing two fields on one form
+        // spent about four seconds waiting for transitions that were never
+        // going to happen, which is most of the gap a user sees between two
+        // fields and none of it is thinking.
+        //
+        // These steps are verified by reading the field back instead — see
+        // `fieldContents` — so the wait only has to cover the keystrokes
+        // landing, not a navigation. A short budget, and no pretence that an
+        // unsatisfied one means anything.
+        const staysPut = graph.STAYS_ON_SCREEN.has(step.action);
         const w = await api.waitFor(deviceQuery, {
           mode: 'settle',
           since: before,
-          stableMs: stillness,
-          timeoutMs: budgetMs,
+          stableMs: staysPut ? Math.min(stillness, STAYS_PUT_STILLNESS_MS) : stillness,
+          timeoutMs: staysPut ? STAYS_PUT_BUDGET_MS : budgetMs,
           options,
         });
         return {
@@ -303,7 +469,7 @@ export async function runScript(
           // What this wait was allowed, and where the number came from. A
           // timeout nobody can explain is how a fixed sleep comes back as a
           // constant with a comment.
-          budgetMs,
+          budgetMs: graph.STAYS_ON_SCREEN.has(step.action) ? STAYS_PUT_BUDGET_MS : budgetMs,
           stillnessMs: stillness,
           quietGapMs: w.quietGapMs,
           // The baseline had already finished moving when the wait began, so it
@@ -385,22 +551,65 @@ export async function runScript(
       // happened. Without this a step that moved the screen the wrong way
       // reports success, and the flow carries on believing it worked.
       let verification = null;
+      // Hoisted because the note below is assembled outside the verification
+      // block that owns `afterScreen`. Reaching into that scope from here threw
+      // `afterScreen is not defined` on the very first step of a real run,
+      // which is what running it on a device catches and reading it does not.
+      let afterReading = null;
       if (verify && ACTION_STEPS.has(step.action) && beforeScreen?.hash) {
         const afterState = (await api.getState(deviceQuery, { options })).state;
         const kind = afterState.transition?.kind;
         const afterScreen = await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs, confirmNovel });
+        afterReading = afterScreen;
         verification = {
-          ...graph.verdict({ udid, prediction, before: beforeScreen.hash, after: afterScreen.hash, kind }),
+          ...withWayBack(
+            stillArriving(
+              belowThreshold(
+                graph.verdict({
+                  udid,
+                  prediction,
+                  before: beforeScreen,
+                  // The whole reading, not just its name: it carries the tokens
+                  // that let `nearestScreen`'s similarity tolerance recognise a
+                  // screen whose content has changed. Passing hashes here is
+                  // what made `unexpected-screen` fire on every run that varied
+                  // its test data.
+                  after: afterScreen,
+                  kind,
+                  action: step.action,
+                }),
+                settled,
+              ),
+              afterScreen,
+            ),
+            { udid, from: beforeScreen, landed: afterScreen },
+          ),
           predicted: prediction ? { to: prediction.to.slice(0, 10), kind: prediction.kind, seen: prediction.count } : null,
           observed: { to: afterScreen.hash?.slice(0, 10), kind },
         };
+        // One more look before "nothing happened" is allowed to stand, because
+        // the map printed below the verdict is a later read and has three times
+        // contradicted it in the same response.
+        verification = await confirmNoChange(deviceQuery, verification, {
+          beforeScreen, options, stableMs, timeoutMs,
+        });
+        if (verification.lateArrival) {
+          // The reading the verdict was taken from is now known to be stale, so
+          // nothing downstream may learn a screen or an edge from it.
+          afterReading = verification.lateArrival;
+          verification.observed = { to: verification.lateArrival.hash?.slice(0, 10), kind };
+          delete verification.lateArrival;
+        }
         // Only remember what was seen on a settled screen: an edge recorded
         // mid-transition points at a screen that never really existed.
         // `confirmed` already means the fingerprint held still across two
         // independent readings, which is the thing `settled` was standing in
         // for. Requiring both meant a screen that settled slowly recorded
         // nothing at all.
-        endScreen = afterScreen;
+        // The late-arrival reading when there was one, because that is the
+        // screen we are actually standing on — recording the stale one would
+        // teach the graph an edge to a screen that had already been replaced.
+        endScreen = afterReading ?? afterScreen;
         // An action with no observed effect teaches the graph nothing, and
         // recording it teaches something false.
         //
@@ -454,7 +663,9 @@ export async function runScript(
       const launchNote = step.action === 'launch' && settled?.noVisibleChange
         ? ' [the screen did not change, so this app was already in front — or it did not come forward]'
         : '';
+      const filling = stillFillingIn(afterReading?.entry);
       const note = launchNote
+        + (filling ? ` [settled, but ${filling} — waitFor content, do not act on this yet]` : '')
         + (settled?.smallChange ? ' [a small change, in one region only]' : '')
         + (settled?.noVisibleChange ? ' [no visible change]' : '')
         + (settled?.staleBaseline ? ' [baseline had already settled; re-taken from the live screen]' : '')
@@ -470,7 +681,33 @@ export async function runScript(
         detail: `${detail}${note}${wrongTurn ? ` [${verification.verdict}: ${verification.detail}]` : ''}`,
         settled,
       });
-      const halt = haltDecision({ verification, stopOnUnexpected, continueOnError });
+      // A variant that satisfies the next step is a note, not a halt.
+      //
+      // Reported twice in one round, and it is the direct cause of two flows
+      // needing three calls instead of one. A tap landed on a *hash variant* of
+      // the screen the edge remembered — the action had plainly worked, the
+      // state was right, the CTA was enabled — and 26 remaining steps were
+      // thrown away. Variant absorption cannot help once the variant has been
+      // recorded as a node of its own, because absorption only claims an
+      // unclaimed reading, so the mismatch becomes permanent.
+      //
+      // The evidence that settles it is the flow itself: if the next step's
+      // target is on the screen we actually reached, we are somewhere the plan
+      // can continue from, whatever the fingerprint thinks. That costs one
+      // resolve on a path that otherwise costs a whole round trip, and it does
+      // not soften the verdict — the mismatch is still reported and still
+      // logged, because it is still the thing that found a real bug for a
+      // reporter twice.
+      const canContinue = await stillOnPlan(deviceQuery, verification, steps[i + 1], options);
+      const halt = haltDecision({
+        verification: canContinue ? { ...verification, verdict: 'unverified' } : verification,
+        stopOnUnexpected,
+        continueOnError,
+      });
+      if (canContinue) {
+        results[results.length - 1].detail +=
+          ` [landed on a variant of the expected screen; the next step resolves here, so continuing]`;
+      }
       if (verification?.verdict) verdicts.push(verification.verdict);
       if (metrics.ESCALATING_VERDICTS.has(verification?.verdict)) {
         noteEscalation({
@@ -478,6 +715,11 @@ export async function runScript(
           fingerprint: beforeScreen?.hash ?? null,
           reason: 'verification_failed',
           candidates: [],
+          // `verification_failed` is the largest reason class in the log and it
+          // was the only one carrying no intent, which made most of the corpus
+          // useless for asking what kind of decision costs us. The step knows
+          // what was asked for; there is no reason to drop it here.
+          intent: goalOf(step),
           // A halted run is a decision simframe made and stopped on; a step
           // that moved nothing carries on and leaves the judgement to whoever
           // reads the result.
@@ -505,12 +747,39 @@ export async function runScript(
         reason: why.reason,
         candidates: why.candidates,
         tried: why.tried,
+        // Carried from the throw site where it exists, and otherwise the step's
+        // own target — which is what was asked for either way.
+        intent: why.intent ?? goalOf(step),
         outcome: 'failed',
         wallMs: Date.now() - stepStart,
         detail: err.message,
       });
       failed = true;
       if (!continueOnError) break;
+      // Nothing downstream of a navigation that never happened can succeed, and
+      // paying its timeouts one at a time is how `--continueOnError` spent 79
+      // seconds on ten steps that could not possibly work — two `waitFor`s
+      // serving their full 9,000 ms against a screen that had not moved. What
+      // the operator saw was "you look stuck", and they were right.
+      //
+      // The evidence is the screen hash: consecutive failures against an
+      // unchanged screen are not independent attempts, they are one failure
+      // being re-paid. `continueOnError` means "do not stop at the first
+      // problem"; it does not mean "keep going after the screen has stopped
+      // responding to anything".
+      const failedOn = beforeScreen?.hash ?? null;
+      if (failedOn && failedOn === lastFailureScreen) {
+        consecutiveFailures += 1;
+      } else {
+        consecutiveFailures = 1;
+        lastFailureScreen = failedOn;
+      }
+      if (consecutiveFailures >= STUCK_AFTER) {
+        results[results.length - 1].error +=
+          ` — ${consecutiveFailures} consecutive failures on an unchanged screen; stopping rather than paying the remaining timeouts`;
+        failed = true;
+        break;
+      }
     }
   }
 
@@ -550,6 +819,10 @@ export async function runScript(
     totalMs: wallMs,
     ranSteps: results.length,
     totalSteps: steps.length,
+    // Every local ruling, so a wrong one is correctable rather than mysterious.
+    // A `stop` also carries the steps it did not attempt, so the caller resumes
+    // instead of re-planning.
+    supervisions: supervisions.length ? supervisions : undefined,
     frames,
   };
 }
@@ -564,36 +837,1214 @@ export async function runScript(
  * focus — usually fine, since a field that already had focus does not move, but
  * also exactly what a tap that missed looks like, so the caller should be told.
  */
+/**
+ * What the field holds now, read back from the tree after the text commits.
+ *
+ * Reported three rounds running, and the third round is what forced this: the
+ * `type` verdict is wrong in *both* directions. A step that reported a clean
+ * `ok` had silently done nothing, while the step warned about as
+ * `no-visible-change` had landed — anti-correlated with reality, on the one
+ * path where acting on the warning is destructive. An operator who re-types on
+ * that warning doubles the field, and there is no way to clear it.
+ *
+ * A change verdict is the wrong instrument. Typing does not change the screen,
+ * so screen-identity movement can only ever answer a question nobody asked.
+ * The field's own contents answer the real one, and the tree already carries
+ * them — `value` has been on an AX target since MAP_VERSION 9.
+ *
+ * Accessibility only: `value` never comes from OCR, and skipping OCR keeps this
+ * to one cheap read. Best effort — a readback that fails must not fail the
+ * step, because the text may well have landed.
+ */
+async function fieldContents(deviceQuery, target, sent, ctx) {
+  const wanted = alnum(sent);
+  // The cheap pass: the tree alone, which is authoritative whenever it answers.
+  const fromTree = await readbackPass(deviceQuery, target, wanted, ctx, false, FIELD_READBACK_RADIUS);
+  if (fromTree) return fromTree;
+  // The tree did not answer — and on a web view it never will. Safari's page
+  // content is not in the accessibility tree at all; a CI run measured
+  // `0 element(s) from ax` on a fully loaded page. That is not a corner case:
+  // **both** silent successes reported from the field were web fields, where
+  // this whole check has always been a no-op that printed a bare success. So
+  // pay for one OCR read before giving up on knowing.
+  //
+  // This pass may only ever *confirm*. OCR fuses a label with its value
+  // ("Telephone: 5551234567"), and on a sub-1x capture it corrupts glyphs
+  // ("saaiad@example.com"), so a miss here is not evidence of an empty field.
+  // The empty-control branch cannot fire on it either, since an OCR text
+  // element carries no `value` — which is the property that makes this safe.
+  if (!wanted) return null;
+  // And it has to look at a frame from *after* the keystrokes. The tree pass is
+  // read live and in-process, so it never had this problem; OCR runs against
+  // the daemon's last published frame, which on the first try was the frame
+  // from before the paste — so the proof arrived, the text was plainly on
+  // screen, and the check still said unconfirmed. Settle first, briefly.
+  await api.waitFor(deviceQuery, {
+    mode: 'settle', stableMs: 250, timeoutMs: READBACK_SETTLE_MS, options: ctx.options,
+  }).catch(() => null);
+  return readbackPass(deviceQuery, target, wanted, ctx, true, FIELD_READBACK_OCR_RADIUS);
+}
+
+/**
+ * One readback attempt against one sensor.
+ *
+ * `useOcr` also decides what a *miss* is allowed to mean: the tree may deny
+ * (an empty valued control is real evidence of absence), OCR may not.
+ */
+async function readbackPass(deviceQuery, target, wanted, ctx, useOcr, radius) {
+  try {
+    const { entry } = await api.readScreenWith(deviceQuery, { useOcr, options: ctx.options });
+    const near = (entry.targets ?? []).filter(
+      (t) => Math.hypot((t.x ?? 0) - target.x, (t.y ?? 0) - target.y) <= radius,
+    );
+    if (!near.length) return null;
+    // The text may arrive as the control's `value` or as a sibling's label —
+    // a React Native input renders its contents as a separate text node — so
+    // look for what was sent across both before concluding anything. Getting
+    // this wrong is what made the first version of this check fail a step whose
+    // text was visible in the very map the failure returned.
+    for (const t of near) {
+      for (const seen of [t.value, t.label]) {
+        if (!seen) continue;
+        // `includes`, not equals: the caret is OCR'd into the value ("Maryam
+        // Hatami" reads back as "Maryam Hatamil"), and a long value is
+        // truncated by the renderer.
+        if (wanted && alnum(seen).includes(wanted)) {
+          return { value: String(seen), landed: true, focused: Boolean(t.focused) };
+        }
+      }
+    }
+    if (useOcr) return null;
+    // Not found. Only an *empty* valued control is evidence of absence; a
+    // control with no `value` attribute at all is no evidence either way.
+    const valued = near.find((t) => t.value != null);
+    if (valued && String(valued.value) === '') {
+      return { value: '', landed: false, focused: Boolean(valued.focused) };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Journal a write, but only one that was seen to land.
+ *
+ * `back.landed` is the whole gate. An unconfirmed write is not evidence the
+ * value was ever in the field, and journalling one would later announce that
+ * text had "disappeared" when it had never arrived.
+ */
+function journalWrite(udid, step, sent, back, ctx) {
+  if (!back?.landed) return;
+  wrote.record(udid, { selector: step.into, value: sent, screen: ctx?.screen ?? null });
+}
+
+/**
+ * Say when a ref was honoured by its label rather than by its number.
+ *
+ * Never silent. Re-resolving is a recovery, not a fact about the ref, and a
+ * recovery a caller cannot see is the shape of every silent-success bug in this
+ * file — so it names the number, the label it fell back to, and why.
+ */
+export function relabelledNote(found) {
+  const r = found?.relabelled;
+  if (!r) return '';
+  return ` [#${r.ref} was stale, so it was re-resolved by the label it was numbered against,`
+    + ` ${JSON.stringify(String(r.label))} — the number was not honoured, the label was]`;
+}
+
+/** Comparison that ignores what OCR adds — a caret, a stray glyph, spacing. */
+const alnum = (v) => String(v ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
+
+/** How the readback is reported, and whether it contradicts what was sent. */
+export function readbackNote(sent, seen) {
+  // No readback, or a readback that found no valued control: no evidence, and
+  // no evidence is not counter-evidence. The first version of this treated a
+  // missing `value` attribute as an empty field and failed a step whose text was
+  // visible in the same map the failure returned — reported, correctly, as
+  // worse than the verdict it replaced.
+  // ...but silence about it is what made two agents report a confident success
+  // into an empty field. Not failing is right; saying nothing is not. The note
+  // is the whole fix: an unconfirmed write must not read like a confirmed one.
+  if (!seen) {
+    return {
+      note: sent ? ' [unconfirmed — nothing on this screen reads back the field\'s contents]' : '',
+      empty: false,
+      landed: false,
+    };
+  }
+  if (seen.landed) {
+    const v = String(seen.value);
+    const shown = v.length > 60 ? `${v.slice(0, 60)}…` : v;
+    return { note: ` = ${JSON.stringify(shown)}`, empty: false, landed: true };
+  }
+  return { note: ' [the field reads empty]', empty: Boolean(sent), landed: false };
+}
+
+/**
+ * Is this screen still filling in?
+ *
+ * Three times in one reported run, every list in an app arrived *after* the
+ * settle declared the screen stable. `waitFor` on a row label fixes it, but
+ * that requires already knowing a string that only exists once loaded — which
+ * you can only learn by having failed once.
+ *
+ * Two signals, both already in hand and neither previously read. The tree often
+ * publishes the spinner itself: the reporter's own map contained
+ * `#13 element 201,263 loading`. And a list that renders its count before its
+ * rows announces itself — the sharpest case in that round was a `waitFor` on
+ * "Records" satisfied by the header **"21 Records"** while zero of the 21 rows
+ * existed. Even a correctly written wait can be satisfied by a promise of
+ * content rather than by content.
+ */
+const LOADING_LABEL = /^(loading|loading…|loading\.\.\.|please wait|fetching|refreshing)$/i;
+const COUNT_HEADER = /^(\d[\d,]*)\s+(records?|results?|items?|rows?|entries)\b/i;
+/**
+ * The largest promised count that could be a count of rendered rows.
+ *
+ * Above this the header is reporting a total for a list that pages or
+ * virtualises, and the number of rows on screen is unrelated to it.
+ */
+const COUNT_HEADER_MAX = 30;
+
+export function stillFillingIn(entry) {
+  const targets = entry?.targets ?? [];
+  if (!targets.length) return null;
+  for (const t of targets) {
+    if (LOADING_LABEL.test(String(t.label ?? '').trim())) {
+      return 'a control on this screen still reads "loading"';
+    }
+  }
+  const content = targets.filter((t) => (t.region ?? 'content') === 'content' && t.label);
+  for (const t of content) {
+    const m = COUNT_HEADER.exec(String(t.label).trim());
+    if (!m) continue;
+    const promised = Number(String(m[1]).replace(/,/g, ''));
+    // Only when the promised number could plausibly be the number of *rendered*
+    // rows. This is the correction to the whole idea, and it took a peer
+    // ignoring the warning to see it: on a paginated or virtualised list the
+    // header is a **total**, and a total says nothing at all about how many rows
+    // should be on screen. Measured: `a header promises 1232 records and only 43
+    // row(s) are here yet` fired on nearly every step of a list whose correct,
+    // final state was 43 rendered rows. Their verdict is the one that matters —
+    // *"by the fourth occurrence I was ignoring it, which is the failure mode
+    // you least want from a warning."*
+    //
+    // A viewport holds on the order of twenty rows, so beyond a screenful the
+    // count cannot be a render target and this has nothing to say.
+    if (Number.isFinite(promised) && promised >= 3 && promised <= COUNT_HEADER_MAX
+      && content.length < promised / 2) {
+      return `a header promises ${promised} ${m[2].toLowerCase()} and only ${content.length - 1} row(s) are here yet`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The text a type/paste step means to send.
+ *
+ * `value` is the selector when `into` is present and the text when it is not,
+ * and reading it as text either way put a field's own label into the field —
+ * reported as `typed into "Asset*" … = "Asset*"`. Refusing beats guessing here:
+ * typing a selector into a form is a wrong write, which is the one class of
+ * mistake this project treats as worse than a failure.
+ */
+export function textToSend(step) {
+  if (step.into != null) {
+    const text = step.text ?? step.value2 ?? step.with;
+    if (text == null) {
+      throw new Error(
+        `${step.action} into ${JSON.stringify(String(step.into))} needs "text" — `
+        + 'with "into" present, "value" is the selector, so there is nothing to send.',
+      );
+    }
+    return String(text);
+  }
+  return String(step.text ?? step.value ?? '');
+}
+
+/** The current screen hash, or null — used to notice a scroll that moved nothing. */
+async function hashNow(deviceQuery, options) {
+  try {
+    return (await api.screenIdentity(deviceQuery, { options, confirmNovel: false })).hash ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Failures that code can already rule on, so the model is never asked.
+ *
+ * Round 7 measured what happens when it is asked anyway. An element *in the
+ * tree but not in view* got `wait` — while the executor's own error said, in
+ * English, "waiting cannot bring it into view". An *ambiguous selector* got
+ * `stop` once with the false reason "screen is elsewhere", and `wait` on a
+ * later bench run. Both are deterministic: no amount of waiting or repeating
+ * makes a selector unique or scrolls a viewport.
+ *
+ * So they are answered here, and the model's remit narrows to the one class it
+ * has been reliably right about — *has this arrived yet?* On the two real
+ * cases of that shape it answered correctly every time, including the one the
+ * field round missed entirely.
+ *
+ * Narrowing a component to where it is reliable is not a workaround. It is the
+ * same move as Phase 17's no-go: ask the local tier only the questions nothing
+ * cheaper can answer.
+ */
+export function deterministicRuling(err) {
+  const m = String(err?.message ?? '');
+  if (/matches \d+ things on this screen/.test(m)) {
+    return { decision: 'stop', why: 'an ambiguous selector cannot be waited or retried into uniqueness — pass index, or a #ref' };
+  }
+  if (/in the tree but not in view/.test(m)) {
+    return { decision: 'stop', why: 'waiting cannot scroll — the element needs scrollTo, or a swipe' };
+  }
+  if (/refused locally|destructive vocabulary/.test(m)) {
+    return { decision: 'stop', why: 'a local retry may not act on this label' };
+  }
+  return null;
+}
+
+/**
+ * Ask the local supervisor whether the plan can proceed past this failure.
+ *
+ * Everything it needs is already in hand: the step, the failure, what is on
+ * screen, how long the screen has been still, and whatever the plan told it to
+ * expect. It never sees pixels and never chooses an action.
+ *
+ * Its own prose is deliberately not trusted as an explanation. In testing it
+ * returned a correct decision with a reason citing a rule that did not apply,
+ * so the decision is used and the reason is recorded — never presented to the
+ * caller as the ground for what happened. Presenting a confabulated rationale
+ * as fact is the mistake `seek`'s documentation already made once.
+ */
+const SUPERVISOR_WAIT_MS = 4000;
+const SUPERVISOR_RETRY_MS = 900;
+/** A scroll moves at once or not at all; it does not need a transition's budget. */
+const SCROLL_SETTLE_MS = 800;
+
+async function superviseFailure(deviceQuery, { goal, step, expected, err, options }) {
+  if (!supervisor.requested(options)) return null;
+  const settled = deterministicRuling(err);
+  if (settled) return { decision: settled.decision, reason: settled.why, from: 'rule' };
+  try {
+    const map = await view.screenMap(deviceQuery, { options, refresh: false });
+    const stillMs = map.identity?.state?.motion?.stillForMs;
+    return await supervisor.judge({
+      goal,
+      step: `${step.action} ${JSON.stringify(String(step.value ?? step.target ?? step.into ?? step.seek ?? '').slice(0, 60))}`,
+      expected,
+      failure: err.message,
+      screen: (map.rows ?? []).filter((r) => r.label).map((r) => r.label),
+      stillMs,
+      note: stillFillingIn(map.identity?.entry),
+      options,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How long ago the screen last moved, or null if it has been still.
+ *
+ * Used only to tell a timing failure from a naming failure, which is a
+ * distinction every `or` chain in a reported round got wrong.
+ */
+async function recentlyChanged(deviceQuery, options, withinMs = 2500) {
+  try {
+    const { state } = await api.getState(deviceQuery, { options });
+    // `changed` is a boolean and `motion.stillForMs` is the age. Reading
+    // `changed` as a timestamp is a mistake worth naming, because it would have
+    // silently reported "0ms ago" on every still screen and turned this hint
+    // into the opposite of information.
+    if (state?.changed === true) return 0;
+    if (state?.transition?.kind === 'loading') return 0;
+    const still = state?.motion?.stillForMs;
+    if (!Number.isFinite(still)) return null;
+    return still <= withinMs ? Math.round(still) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Try a step's alternatives before giving up on it.
+ *
+ * Four situations the owner gave, one after another, turned out to be one
+ * problem: a location with no assets, a misclicked like, hunting a setting
+ * through an unfamiliar menu tree, a search that returns nothing useful. *"All
+ * done in maybe less than a second or a few seconds."* *"When I don't find what
+ * I need somewhere I don't fall into an existential crisis. I look for it
+ * somewhere else."*
+ *
+ * simframe answered all four the same way: the step threw, the batch was
+ * abandoned, and the reasoner was asked. A step could only succeed or throw, and
+ * throwing costs a round trip — `continueOnError` is all-or-nothing for a whole
+ * run, which is why nobody used it.
+ *
+ * So a step may now carry its own fallbacks:
+ *
+ *     {"tap": "Save", "or": ["Done", "Confirm"]}
+ *
+ * They are tried locally, in order, and only an exhausted list reaches the
+ * model. This lengthens the *batch* instead of multiplying the round trips,
+ * which is the whole objective.
+ *
+ * **Which failures are eligible, and why the list is short.** Only a selector
+ * that did not resolve — "that label is not here, try this one". A step that
+ * resolved and then went somewhere unexpected is *not* eligible: retrying from
+ * the wrong screen is nonsense, and the verdict now names the way back instead.
+ * Getting this wrong turns a retry primitive into a way to hammer an app until
+ * something gives.
+ *
+ * And an alternative is simframe's own initiative, so the destructive
+ * vocabulary applies to it even though it does not apply to the step the caller
+ * wrote. `{"tap": "DELETE"}` is a request and is honoured; substituting
+ * "DELETE" for a "Done" that did not resolve is not.
+ */
+const RESOLVE_FAILURES = new Set(['unknown_screen', 'ambiguous_intent']);
+
+export function alternativesFor(step) {
+  const raw = step?.or ?? step?.orElse ?? step?.alternatives;
+  if (raw == null) return [];
+  const list = Array.isArray(raw) ? raw : [raw];
+  return list.map((v) => (typeof v === 'string' ? v : v?.value ?? v?.target ?? v?.label)).filter(Boolean);
+}
+
+export function mayRetryAfter(err) {
+  const tagged = metrics.escalationOf(err);
+  return Boolean(tagged && RESOLVE_FAILURES.has(tagged.reason));
+}
+
+/**
+ * Which alternatives a local retry is permitted to try, and what was refused.
+ */
+export function permittedAlternatives(step, { locale } = {}) {
+  const allowed = [];
+  const refused = [];
+  for (const label of alternativesFor(step)) {
+    const verdict = vocabulary.mayActLocally(label, { locale });
+    if (verdict.allowed) allowed.push(label);
+    else refused.push({ label, reason: verdict.reason });
+  }
+  return { allowed, refused };
+}
+
+/** The step to run for an alternative: the same step, aimed somewhere else. */
+export function stepWithTarget(step, label) {
+  const next = { ...step };
+  delete next.or;
+  delete next.orElse;
+  delete next.alternatives;
+  for (const key of ['value', 'target', 'label', 'into']) {
+    if (key in step) { next[key] = label; return next; }
+  }
+  next.value = label;
+  return next;
+}
+
+/**
+ * Say the way back, in the same breath as saying we went the wrong way.
+ *
+ * The owner's generalisation of the recovery problem, and it is the right one:
+ * *"I go to Instagram, misclick a like button — humans aren't as accurate as
+ * bots. I notice immediately, I go back or I remove the like. No need to think
+ * for minutes and scan the whole of Instagram's philosophy. I use what I see."*
+ *
+ * That recovery needs no knowledge of the app at all. It needs to notice, and
+ * to know the way back — and simframe already has both. `unexpected-screen`
+ * notices in about 200ms, and `graph.route` can compute a path from where we
+ * landed to where we were, from edges already recorded.
+ *
+ * It just never said so. The step threw, the batch died, and a model round trip
+ * was spent deciding something the graph could already answer. This does not
+ * remove the round trip — going back changes what happens next, so a person
+ * should still choose it — but it makes one round trip sufficient instead of the
+ * three to six the field reports spent working out where they were.
+ */
+export function wayBack(udid, from, landed, { graph: g = graph } = {}) {
+  const fromHash = typeof from === 'string' ? from : from?.hash;
+  const landedHash = typeof landed === 'string' ? landed : landed?.hash;
+  if (!udid || !fromHash || !landedHash || fromHash === landedHash) return null;
+  let path;
+  try {
+    path = g.route(udid, landedHash, fromHash, { maxDepth: 3 });
+  } catch {
+    return null;
+  }
+  if (!path?.length) return null;
+  const steps = path.map((e) => {
+    const st = e.step ?? {};
+    const label = st.value ?? st.target ?? st.label ?? st.into;
+    return label ? `${st.action ?? 'tap'} ${JSON.stringify(String(label).slice(0, 28))}` : (st.action ?? 'tap');
+  });
+  return `back to where you were: ${steps.join(' then ')}`
+    + (path.length === 1 && path[0].count > 1 ? ` (seen ${path[0].count}x)` : '');
+}
+
+/**
+ * Do not call a screen a wrong turn while it is still arriving.
+ *
+ * `unexpected-screen` fired three times in one reported run and was wrong all
+ * three. One cause was this: a tap applied a selection correctly and enabled
+ * the submit button, but an async panel on the same screen had not come back
+ * yet, so the structure differed from the settled screen the edge remembered.
+ * Nothing had gone wrong; the screen was half there.
+ *
+ * A settle can be satisfied while content is still loading — that is Phase
+ * 11.5's finding and the reason `loading` exists — so the two must be read
+ * together. An incomplete screen cannot contradict a prediction, and
+ * `unverified` is the honest verdict: we do not know yet.
+ *
+ * The other cause was data variation, which this does not address: picking a
+ * different test asset changes the content and the check reads it as a wrong
+ * turn. That needs structural comparison and is filed, not fixed.
+ */
+export function withWayBack(verification, { udid, from, landed, graph: g } = {}) {
+  if (verification?.verdict !== 'unexpected-screen') return verification;
+  const route = wayBack(udid, from, landed, g ? { graph: g } : undefined);
+  return route ? { ...verification, detail: `${verification.detail} — ${route}` } : verification;
+}
+
+export function stillArriving(verification, afterScreen) {
+  if (verification?.verdict !== 'unexpected-screen') return verification;
+  if (afterScreen?.loading !== true) return verification;
+  return {
+    ...verification,
+    verdict: 'unverified',
+    detail: 'the screen this reached is still loading, so it cannot be compared yet'
+      + ' — re-read it, or waitFor the content you expect, before treating this as a wrong turn',
+  };
+}
+
+/**
+ * Can the plan continue from where we actually landed?
+ *
+ * Only asked when the verdict is `unexpected-screen`, and only answered by the
+ * next step's own selector resolving here. A screen that can serve the next step
+ * is not a wrong turn in any sense the caller cares about.
+ */
+async function stillOnPlan(deviceQuery, verification, nextStep, options) {
+  if (verification?.verdict !== 'unexpected-screen' || !nextStep) return false;
+  const target = nextStep.value ?? nextStep.target ?? nextStep.label ?? nextStep.into;
+  // A coordinate resolves anywhere and a ref was numbered on another screen, so
+  // neither is evidence about where we are.
+  if (!target || /^#\d+$/.test(String(target).trim()) || /^@?-?\d+\s*,\s*-?\d+$/.test(String(target).trim())) return false;
+  if (!ACTION_STEPS.has(nextStep.action) && nextStep.action !== 'assert' && nextStep.action !== 'waitFor') return false;
+  try {
+    const hit = await api.locate(deviceQuery, String(target), { options });
+    return Boolean(hit?.target);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reconcile the two sensors when they disagree about "did anything happen".
+ *
+ * The wait watches regions and the verdict compares screen identity, so a tap
+ * that moved one cell produced `[a small change, in one region only]` and
+ * `no-visible-change: the screen did not change` four lines apart. Both were
+ * true of different questions, and the pair reads as a contradiction rather
+ * than as a measurement.
+ *
+ * The verdict stands — a change too small to move the screen's identity is the
+ * finding — but it should say what was actually observed.
+ */
+/**
+ * How long a "nothing happened" verdict waits before believing itself.
+ *
+ * Short, because it is paid on a path that is currently often wrong: three
+ * `no-visible-change` verdicts in one field round were contradicted by the
+ * element list printed directly beneath them.
+ */
+const LATE_CHANGE_MS = 700;
+
+/**
+ * Give a "nothing happened" verdict one more look before it stands.
+ *
+ * The verdict reads the screen's identity, and the map underneath it is a
+ * separate, later read — so a web view or a slow list can render in between,
+ * and then the response contradicts itself. Reported from the field, three
+ * times in one round: `no-visible-change: the screen did not change` above a
+ * map whose hash had moved `46a0a26d → 1a8e8be1` and which listed three
+ * dropdown options that had just appeared. The agent's summary of the cost is
+ * the reason this is worth a re-read: *"I was instructed to spend a call
+ * disproving a claim the same response had already disproved."*
+ *
+ * It is also the verdict that must not be wrong in this direction. It escalates
+ * — the hint line tells the caller to stop and check — so a false one buys a
+ * round trip every time, which is exactly what this project is built to remove.
+ *
+ * The test is provable rather than heuristic: if the screen is now different
+ * from how it was *before* the action, the action changed it.
+ */
+async function confirmNoChange(deviceQuery, verification, { beforeScreen, options, stableMs, timeoutMs }) {
+  if (verification?.verdict !== 'no-visible-change' || !beforeScreen?.hash) return verification;
+  await api.waitFor(deviceQuery, {
+    mode: 'settle', stableMs: 250, timeoutMs: LATE_CHANGE_MS, options,
+  }).catch(() => null);
+  const again = await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs }).catch(() => null);
+  if (!again?.hash || again.hash === beforeScreen.hash) return verification;
+  return {
+    ...verification,
+    verdict: 'unverified',
+    detail: 'the screen did change, but not until after the verdict had been taken'
+      + ` (${beforeScreen.hash.slice(0, 8)} → ${again.hash.slice(0, 8)})`
+      + ' — a web view or a slow list can render after a settle has reported it still',
+    lateArrival: again,
+  };
+}
+
+export function belowThreshold(verification, settled) {
+  if (verification?.verdict !== 'no-visible-change' || !settled?.smallChange) return verification;
+  return {
+    ...verification,
+    detail: 'the screen changed in one region only, by too little to be a different screen'
+      + ' — if that was the whole effect, this is fine; if a transition was expected, it did not happen',
+  };
+}
+
+/**
+ * Is the field focused? One read, and the answer is advisory.
+ *
+ * Filling one field used to be verified five times: the field exists, it took
+ * focus, the text landed, the screen settled, the screen is still the screen.
+ * None of that involves a model — it is all local — which is why several
+ * seconds could pass between two fields with no thinking in them at all.
+ *
+ * Two of the five were change-based waits, and an action that changes nothing
+ * cannot satisfy one: measured on a still screen, 1.9-2.0 seconds each, both
+ * returning `satisfied: false`. Tapping into a text field barely moves the
+ * screen, and with a hardware keyboard attached to the simulator no software
+ * keyboard appears, so there is often nothing to see.
+ *
+ * The collapse is to verify the *result* rather than each precondition. If the
+ * text landed, focus obviously worked, so checking focus first is redundant
+ * with checking the outcome. This stays as a single ~85 ms accessibility read
+ * because typing into an unfocused field loses the keystrokes, so it is worth
+ * one cheap look — but it never blocks and it never fails the step. The
+ * readback after typing decides.
+ */
+async function focusHint(deviceQuery, target, ctx) {
+  try {
+    const { entry } = await api.readScreenWith(deviceQuery, { useOcr: false, options: ctx.options });
+    let elsewhere = false;
+    for (const t of entry.targets ?? []) {
+      if (t.focused !== true) continue;
+      if (Math.hypot((t.x ?? 0) - target.x, (t.y ?? 0) - target.y) <= FIELD_READBACK_RADIUS) {
+        return { focused: true, elsewhere: false };
+      }
+      elsewhere = true;
+    }
+    return { focused: false, elsewhere };
+  } catch {
+    return { focused: false, elsewhere: false };
+  }
+}
+
+/**
+ * How long to wait for the tap to become focus before inserting text.
+ *
+ * Paid only when the tree has not yet said the field is focused, so a field
+ * that focuses instantly costs one read exactly as before.
+ */
+const FOCUS_WAIT_MS = 700;
+const FOCUS_POLL_MS = 80;
+
+/**
+ * Wait for focus to arrive, without treating silence as failure.
+ *
+ * External research settled a symptom two agents reported independently and
+ * neither could reproduce: one insertion primitive returns `ok` into an empty
+ * field, and the other then works. It is a **focus race**, not a defect in
+ * either primitive — a keystroke delivered before a web view commits focus to
+ * its input is simply dropped, and WDA copes by checking `hasKeyboardFocus`
+ * before typing. So the investigation everyone reached for, paste versus type,
+ * was the wrong one and would never have converged.
+ *
+ * The wait ends the moment the tree names our target as focused. If the budget
+ * runs out with the tree saying nothing, we insert anyway — because "the tree
+ * is silent about focus" has never been evidence the tap missed, and this file
+ * has been wrong in that direction before.
+ */
+async function awaitFocus(deviceQuery, target, ctx) {
+  const deadline = Date.now() + FOCUS_WAIT_MS;
+  let last = await focusHint(deviceQuery, target, ctx);
+  while (!last.focused && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, FOCUS_POLL_MS));
+    last = await focusHint(deviceQuery, target, ctx);
+  }
+  return last;
+}
+
 async function focusField(deviceQuery, udid, step, ctx) {
   const found = await api.locate(deviceQuery, step.into, { index: step.index, refresh: step.refresh });
-  // What this field has cost to focus before, on this screen. Cold, or with no
-  // verification running, that is exactly the three constants above; measured,
-  // it can only be longer. `graph.focusPlan` carries the reason it is either.
-  const plan = ctx.focus?.plan ?? {
-    reactionMs: FOCUS_REACTION_MS, timeoutMs: FOCUS_TIMEOUT_MS, cold: true, from: 'no timing in hand',
-  };
   const tappedAt = Date.now();
   await input.tapPoint(udid, found.target.x, found.target.y);
-  const focused = await api.waitFor(deviceQuery, {
-    mode: 'settle',
-    stableMs: FOCUS_STABLE_MS,
-    reactionMs: plan.reactionMs,
-    timeoutMs: plan.timeoutMs,
-    options: ctx.options,
-  });
-  // Only a wait that was satisfied is a measurement of how long focus takes. A
-  // reaction window that ran out measures how long we were prepared to watch a
-  // screen that did not move, and banking that would teach the edge the cost of
-  // its own impatience — the estimator mistake learned stillness made.
-  if (ctx.focus && focused.satisfied) ctx.focus.observedMs = Date.now() - tappedAt;
+  const focused = await awaitFocus(deviceQuery, found.target, ctx);
+  // There IS a focus wait again, and this comment used to say there was not.
+  // It was removed when one accessibility read replaced it, which was right for
+  // native fields and wrong for web views: a keystroke delivered before a web
+  // view commits focus is dropped, and that is the whole explanation of the
+  // intermittent silent write two agents reported. The wait is bounded, it ends
+  // the moment the tree names the target as focused, and silence still means
+  // proceed — see `awaitFocus`.
+  //
+  // The focus *distribution* is still not collected, and that part stands:
+  // banking the duration of these polls under the old name would keep a number
+  // nobody uses, measuring something other than what its name says, which is
+  // the shape of the learned-stillness mistake. `graph.focusPlan` and the
+  // `focusSamples` it reads stay in place, unfed; if nothing claims them they
+  // should go.
+  void tappedAt;
   return {
     found,
     where: `"${found.target.label}" at ${found.target.x},${found.target.y}`,
-    quiet: focused.satisfied ? '' : ' [the field did not visibly take focus]',
-    waited: focused.satisfied && !plan.cold ? ` [focus in ${focused.waitedMs}ms, ${plan.from}]` : '',
+    // Only claimed when the tree named a *different* focused element. "The
+    // tree says nothing about focus" is not evidence the tap missed, and
+    // asserting it from a screen that simply did not move is what made this
+    // note wrong on a correctly focused field.
+    // Only claimed when the tree named a *different* focused element. Silence
+    // about focus is not evidence the tap missed, and asserting it from a
+    // screen that simply did not move is what made this note wrong on a
+    // correctly focused field.
+    quiet: focused.elsewhere && !focused.focused ? ' [focus is on another element of this screen]' : '',
   };
 }
 
+/**
+ * Look for something that is not on this screen, the way a person does.
+ *
+ * The owner's description, and it is the behaviour this implements: *"I am in a
+ * new app's settings, I look for something like change username. I go to each
+ * menu, check the items, nothing like that? Next menu, until I find it."* And:
+ * *"when I don't find what I need somewhere, I don't fall into an existential
+ * crisis. I look for it somewhere else."*
+ *
+ * Today a miss is an existential crisis — nothing resolves, the step throws, the
+ * batch dies, and the reasoner is asked. Twelve of 173 escalations, each one
+ * stopping a batch, so a five-menu hunt costs ten or more round trips for
+ * something a person does in seconds.
+ *
+ * `seek` opens containers, checks, and comes back, inside a hard budget.
+ *
+ * **It acts, and saying otherwise is what made it dangerous.** The first
+ * version of this comment said it "finds and does not act", meaning it does not
+ * tap the *target* — but opening a door is an action, doors change state, and a
+ * reader who trusted that sentence handed `seek` a flow it could destroy. It
+ * did: it opened CANCEL, then AI TROUBLESHOOTING, then pressed "YES, THIS FIXED
+ * MY PROBLEM", ending five screens deep in a live support chat with a
+ * half-completed service request gone. One label further along was SUBMIT
+ * SERVICE REQUEST.
+ *
+ * What is true: it does not tap the target — it leaves you on the screen where
+ * the target resolves and says so, and the caller taps it as the next step of
+ * the same batch. What it *does* tap is doors, filtered by the exploration
+ * vocabulary (`vocabulary.openableAsDoor`), which is much stricter than the
+ * substitution list and refuses anything that commits, abandons, answers or
+ * leaves. And it returns to the screen it started from before handing back,
+ * saying plainly when it could not.
+ *
+ * Ordering is the pluggable part, and the only part a local model touches. With
+ * `SIMFRAME_PLANNER` unset the order is mechanical — the screen's own reading
+ * order — and every candidate gets tried anyway; the model only changes which
+ * comes first. That is why it is safe to try and why it is A/B-testable: run the
+ * same flow with the flag off and on and compare steps to target.
+ */
+export const SEEK_BUDGET = 6;
+
+/** How many candidates a ranker is asked about, and how long a door gets to open. */
+export const SEEK_RANK_CANDIDATES = 12;
+/** How many back-steps a failed seek may spend returning to where it began. */
+const RETURN_BUDGET = 8;
+/** How long a disagreeing assert waits before looking again. */
+const ASSERT_RETAKE_MS = 900;
+/** Consecutive failures on one unchanged screen before a continue-on-error run gives up. */
+export const STUCK_AFTER = 3;
+const SEEK_SETTLE_MS = 1200;
+
+async function candidatesToOpen(deviceQuery, udid, { visited, options }) {
+  const map = await view.screenMap(deviceQuery, { options, refresh: true });
+  const here = map.identity?.hash ?? null;
+  const labels = [];
+  for (const r of map.rows ?? []) {
+    // Content only. A nav-bar title is not a door — the first version of this
+    // opened "Settings", which is the name of the screen it was already on.
+    if ((r.region ?? 'content') !== 'content') continue;
+    if (!r.label || r.enabled === false) continue;
+    if (visited.has(String(r.label))) continue;
+    // Permissive about *shape*, strict about *vocabulary* — and that pairing is
+    // the correction, not a loosening. Requiring `actsInteractive` found **zero
+    // doors** on a screen holding two real pickers, because a React Native
+    // picker is a generic element with no value and the tree has been wrong
+    // about roles in every round. Meanwhile the door vocabulary was too loose
+    // and opened CANCEL. The tree is unreliable about what is tappable and the
+    // label is reliable about what must not be opened, so trust each where it
+    // is trustworthy.
+    if (!vocabulary.openableAsDoor(r.label)) continue;
+    // A paragraph is not a door.
+    if (String(r.label).length > 48) continue;
+    labels.push(String(r.label));
+  }
+  return { here, map, labels: [...new Set(labels)] };
+}
+
+/**
+ * Get back to the screen above, by whatever means this app offers.
+ *
+ * This is where `seek` first stranded itself, on a finding already in
+ * DEFERRED: the nav-bar back chevron is invisible to simframe, so
+ * `locate("back")` throws and one door was all it ever opened. The left-edge
+ * gesture needs no label and works on any pushed screen, so it is the fallback
+ * rather than the exception — and the return is confirmed, because a swipe that
+ * did nothing would make the next candidate a tap on a screen we did not mean
+ * to be on.
+ */
+async function goBack(deviceQuery, udid, step, ctx, { from, to }) {
+  const byLabel = await (async () => {
+    try {
+      const route = from && to ? graph.route(udid, from, to, { maxDepth: 1 }) : null;
+      const st = route?.length === 1 ? route[0].step ?? {} : {};
+      const label = st.value ?? st.target ?? st.label;
+      return label && vocabulary.actableLocally(label) ? String(label) : 'back';
+    } catch {
+      return 'back';
+    }
+  })();
+  let acted = false;
+  try {
+    const b = await api.locate(deviceQuery, byLabel, { options: ctx.options });
+    await input.tapPoint(udid, b.target.x, b.target.y);
+    acted = true;
+  } catch { /* no visible back control — use the gesture */ }
+  if (!acted) {
+    try {
+      const geo = await ctx.screen();
+      const y = Math.round((geo.pointHeight ?? 874) / 2);
+      await input.swipe(udid, { x: 2, y }, { x: Math.round((geo.pointWidth ?? 402) * 0.6), y }, { durationMs: 250 });
+      acted = true;
+    } catch {
+      return false;
+    }
+  }
+  await api.waitFor(deviceQuery, { mode: 'settle', stableMs: step.stableMs ?? 400, timeoutMs: step.timeoutMs ?? SEEK_SETTLE_MS, options: ctx.options });
+  try {
+    const now = await api.screenIdentity(deviceQuery, { options: ctx.options, confirmNovel: false });
+    return Boolean(now.hash) && now.hash !== from;
+  } catch {
+    return false;
+  }
+}
+
+async function seek(deviceQuery, udid, step, ctx) {
+  const goal = step.seek ?? step.value ?? step.target;
+  if (!goal) throw new Error('usage: {"seek": "what you are looking for"}');
+  const budget = Math.max(1, Math.min(step.budget ?? SEEK_BUDGET, 12));
+  const options = ctx.options;
+
+  const found = async () => {
+    try {
+      const r = await api.locate(deviceQuery, String(goal), { options });
+      return r?.target ? r : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const already = await found();
+  if (already) return `"${goal}" is already here: "${already.target.label}" at ${already.target.x},${already.target.y}`;
+
+  // Keyed on the label alone, not label-per-screen. Keying it per screen let it
+  // cycle — General, About, General, Screen Capture, General, About — because a
+  // list's identity is not perfectly stable across a return to it, so the same
+  // door read as unvisited. Within one seek, one attempt per label is enough.
+  const visited = new Set();
+  const opened = [];
+  const trail = [];
+  let spent = 0;
+  const origin = await (async () => {
+    try {
+      return (await api.screenIdentity(deviceQuery, { options, confirmNovel: false })).hash ?? null;
+    } catch {
+      return null;
+    }
+  })();
+
+  // Depth-first, because that is what a person does: Accessibility, then
+  // Display & Text Size, then Larger Text. The first version always came back
+  // after one probe and could never reach anything two levels down, which is
+  // where most settings live.
+  while (spent < budget) {
+    const { here, labels } = await candidatesToOpen(deviceQuery, udid, { visited, options });
+    if (!labels.length) {
+      // Nothing new here. Back out to the screen above and try its next door.
+      if (!trail.length) break;
+      const to = trail.pop();
+      if (!await goBack(deviceQuery, udid, step, ctx, { from: here, to })) break;
+      continue;
+    }
+    // Only the first handful go to the ranker. A forty-label prompt costs more
+    // to answer and the budget will never reach the tail anyway; and the model
+    // is asked about candidates, not given the screen.
+    const asked = labels.slice(0, SEEK_RANK_CANDIDATES);
+    const ranked = await planner.rank(String(goal), asked, { deviceOptions: options });
+    const ordered = ranked ? [...ranked, ...labels.slice(SEEK_RANK_CANDIDATES)] : labels;
+    const pick = ordered[0];
+    visited.add(pick);
+    spent += 1;
+
+    try {
+      const door = await api.locate(deviceQuery, pick, { options });
+      await input.tapPoint(udid, door.target.x, door.target.y);
+    } catch {
+      continue; // a label that will not resolve is not a door
+    }
+    await api.waitFor(deviceQuery, { mode: 'settle', stableMs: step.stableMs ?? 400, timeoutMs: step.timeoutMs ?? SEEK_SETTLE_MS, options });
+
+    let landed = null;
+    try {
+      landed = (await api.screenIdentity(deviceQuery, { options, confirmNovel: false })).hash;
+    } catch { /* unknown where we are; the found() check still decides */ }
+    // A door that led nowhere is not a door, and descending would corrupt the
+    // trail with a screen we never left.
+    if (landed && landed !== here) trail.push(here);
+
+    const hit = await found();
+    if (hit) {
+      return `found "${goal}" as "${hit.target.label}" at ${hit.target.x},${hit.target.y}`
+        + ` after opening ${opened.concat(pick).map((l) => JSON.stringify(l)).join(' -> ')}`
+        + ` (${spent} of ${budget} step(s)${planner.requested(options) ? ', planner-ordered' : ''})`;
+    }
+    opened.push(pick);
+  }
+
+  // Come back before handing over.
+  //
+  // The contract is depth-first *with return*, and on failure it was not: a
+  // reported run ended five doors deep in a live support chat, on an unrelated
+  // screen, with the flow it started from destroyed. Leaving a caller somewhere
+  // they did not ask to be is worse than failing, because everything they try
+  // next is aimed at the wrong screen.
+  let restored = origin == null;
+  for (let i = 0; i < RETURN_BUDGET && !restored; i += 1) {
+    let now = null;
+    try {
+      now = (await api.screenIdentity(deviceQuery, { options, confirmNovel: false })).hash;
+    } catch { break; }
+    if (now === origin) { restored = true; break; }
+    if (!await goBack(deviceQuery, udid, step, ctx, { from: now, to: origin })) break;
+  }
+
+  // Say where we got to and what is there, not just that we failed.
+  //
+  // Measured on the first real run of this: with the ranker on, `seek "make the
+  // text bigger"` went Accessibility -> Display & Text Size in two steps — the
+  // right place — and then reported "not found", because the control is called
+  // "Larger Text" and `locate` matches labels lexically. The navigation was
+  // right and the arrival was unreportable, so the caller learned nothing from a
+  // 20-second search.
+  //
+  // The whole point of a local tier is to make ONE round trip sufficient. So the
+  // hand-back carries the landing: where we are, and what is on it.
+  const landing = await (async () => {
+    try {
+      const map = await view.screenMap(deviceQuery, { options, refresh: false });
+      const here = (map.rows ?? [])
+        .filter((r) => (r.region ?? 'content') === 'content' && r.label)
+        .slice(0, 12)
+        .map((r) => JSON.stringify(String(r.label).slice(0, 32)));
+      return here.length ? ` Now on ${map.name ? `"${map.name}"` : (map.identity?.hash ?? 'an unnamed screen').slice(0, 8)}, which offers: ${here.join(', ')}.` : '';
+    } catch {
+      return '';
+    }
+  })();
+  throw metrics.tag(
+    new Error(
+      `"${goal}" did not resolve by label within ${spent} of ${budget} steps.`
+      + (opened.length ? ` Opened: ${opened.map((l) => JSON.stringify(l)).join(' -> ')}.` : ' Nothing here looked like a container.')
+      + landing
+      + (restored
+        ? ' Back on the screen you started from.'
+        : ' **You are not back where you started** — the way back could not be found, so read the screen before acting.')
+      + ' If one of those is what you meant, tap it by name; otherwise say where to look or raise the budget.',
+    ),
+    'no_plan',
+    { intent: String(goal), tried: opened },
+  );
+}
+
+/**
+ * How far the screen actually moved, measured from the elements themselves.
+ *
+ * The missing sensor, and the owner named the need exactly: *"you have to find a
+ * way to detect where you currently are, so when you are already on top you
+ * don't scroll further, or the bottom."* Nothing on either platform reports a
+ * scroll offset, so it has to be inferred — and the two signals tried before
+ * this both failed on a real page.
+ *
+ * The **screen hash** changes forever on a page whose footer has live content,
+ * so "the hash stopped changing" never fired and a sweep thrashed at the bottom
+ * for forty seconds. **New labels** fail the other way: a gesture that reveals
+ * only a little adds nothing new and looks like an end, which stopped a sweep
+ * two sections above the form it was looking for.
+ *
+ * Element geometry answers it directly. Take the labels present both before and
+ * after, and compare their y. Unchanged means nothing moved — that is an end,
+ * whatever the hash or the label set says. A negative median delta means the
+ * content came up, so we travelled down, and by how much.
+ */
+export const SCROLL_STILL_PX = 6;
+
+export function scrollDelta(before, after) {
+  // Content only. Fixed chrome is the trap: a browser's bottom toolbar is five
+  // elements whose y never changes, and with few shared content rows they drag
+  // the median to zero — so a page that had plainly scrolled measured as
+  // motionless and a sweep declared the bottom after one section. Only things
+  // that can move are evidence that something moved.
+  const scrolls = (r) => {
+    const region = r?.region ?? 'content';
+    return region !== 'nav-bar' && region !== 'tab-bar' && region !== 'status-bar' && region !== 'keyboard';
+  };
+  const was = new Map();
+  for (const r of before ?? []) {
+    if (!scrolls(r)) continue;
+    const k = alnum(r.label);
+    if (k && Number.isFinite(r.y) && !was.has(k)) was.set(k, r.y);
+  }
+  const deltas = [];
+  for (const r of after ?? []) {
+    if (!scrolls(r)) continue;
+    const k = alnum(r.label);
+    if (!k || !Number.isFinite(r.y) || !was.has(k)) continue;
+    deltas.push(r.y - was.get(k));
+  }
+  if (!deltas.length) {
+    // Nothing in common. Either everything changed — a real move — or the read
+    // failed; either way this is not evidence of an end.
+    return { moved: null, px: null, shared: 0 };
+  }
+  deltas.sort((a, b) => a - b);
+  const median = deltas[deltas.length >> 1];
+  return {
+    moved: Math.abs(median) > SCROLL_STILL_PX,
+    px: Math.round(median),
+    shared: deltas.length,
+  };
+}
+
+/**
+ * Sweep a scrollable screen section by section, and fill what is there.
+ *
+ * The owner's algorithm: *"to scan a scrollable screen and fill, you need to
+ * detect min/max scroll and look at it section by section. Section 1: anything
+ * to fill? Do it. Not? Scroll to section 2."*
+ *
+ * That is the right shape for a reason `scrollTo` cannot fix. The tree publishes
+ * what is rendered, so a long form is only ever knowable in pieces — and one
+ * gesture travels a non-deterministic distance (four rows once, one row the
+ * next), so "jump to section 3" is not a thing that exists. Acting on whatever
+ * the current viewport holds is the only plan that survives that.
+ *
+ * **Both ends are detected, and by the right signal.** The first version keyed
+ * on the screen hash and ran its whole budget on a page whose footer has live
+ * content: the hash kept changing, so "stopped moving" never fired, and the
+ * operator watched it thrash at the bottom for forty seconds. A section that
+ * contributes **no new elements** is the end, whatever the hash says.
+ *
+ * **And it starts at the beginning**, because a sweep from an unknown position
+ * covers an unknown amount — the same forty seconds began with section 1 being
+ * the page footer. Going up is bounded and still wants two stalls, but the
+ * gesture that confirms the second one is a 60pt nudge rather than a full
+ * section: a section-sized up-swipe at the top of a web page is
+ * pull-to-refresh, and a reload clears the form the sweep exists to fill.
+ */
+export const SWEEP_SECTIONS = 10;
+
+const sweepKey = (r) => `${alnum(r.label)}\u0000${Math.round((r.x ?? 0) / 8)}`;
+
+async function sectionHere(deviceQuery, options) {
+  try {
+    const map = await view.screenMap(deviceQuery, { options, refresh: true });
+    return (map.rows ?? []).filter((r) => r.label);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Advance by a section, not by whatever a default swipe happens to do.
+ *
+ * Measured on a real page: `{"scroll":"down"}` moved **28, 42 and 58 points** on
+ * an 874-point screen — about five per cent of a viewport per gesture. Covering
+ * a page that way takes dozens of swipes, which is precisely what the operator
+ * was watching: *"I still see scroll thrashing, you scrolled too much."* Too
+ * many gestures, not too far each.
+ *
+ * A section is a viewport. `SECTION_FRACTION` leaves a band of overlap so
+ * nothing falls between two reads, which is the whole reason to sweep rather
+ * than to jump.
+ */
+const SECTION_FRACTION = 0.7;
+
+/**
+ * How far the gesture that *confirms* the top travels.
+ *
+ * Small on purpose. iOS Safari's pull-to-refresh fires on overscroll distance,
+ * and a section-sized up-swipe drags roughly 600 points — at the top that is an
+ * enormous overscroll and it reloads the page. Sixty points still moves a page
+ * that has anywhere left to go, which is all the confirmation needs to do, and
+ * stays well under the refresh threshold when it does not.
+ */
+const TOP_CONFIRM_PT = 60;
+
+async function scrollOne(deviceQuery, udid, dir, ctx, { spanPt } = {}) {
+  const geo = await ctx.screen();
+  const h = geo?.pointHeight ?? 874;
+  const x = Math.round((geo?.pointWidth ?? 402) / 2);
+  const span = spanPt ? Math.round(spanPt) : Math.round(h * SECTION_FRACTION);
+  const top = Math.round(h * 0.12);
+  const from = dir === 'up' ? { x, y: top } : { x, y: top + span };
+  const to = dir === 'up' ? { x, y: top + span } : { x, y: top };
+  try {
+    await input.swipe(udid, from, to, { durationMs: 260 });
+  } catch {
+    // A platform without a swipe still has a scroll.
+    await runStep(deviceQuery, udid, { action: 'scroll', value: dir }, ctx);
+  }
+  await api.waitFor(deviceQuery, {
+    mode: 'stable', stableMs: 200, timeoutMs: SCROLL_SETTLE_MS, options: ctx.options,
+  }).catch(() => null);
+}
+
+async function sweep(deviceQuery, udid, step, ctx) {
+  const limit = Math.max(1, Math.min(step.sections ?? SWEEP_SECTIONS, 20));
+  const options = ctx.options;
+  const fill = step.fill && typeof step.fill === 'object' ? { ...step.fill } : null;
+  const wanted = typeof step.sweep === 'string' && step.sweep !== 'all' ? step.sweep.trim() : null;
+
+  // To the beginning, unless told otherwise. Bounded, and it still wants two
+  // stalls before believing the top — a sticky element inside a page can make a
+  // single median read as zero, which is why one stall used to send it from the
+  // top straight to the end without reading the form between.
+  //
+  // What changed is the gesture that buys the second stall. It used to be
+  // another section-sized up-swipe, i.e. a ~600pt drag downward from the very
+  // top of a web page, which is pull-to-refresh: it reloads, and a reload
+  // clears every field the sweep is about to fill. A peer called `sweep "all"`
+  // on a half-filled form "a live grenade" for exactly this, and their run
+  // logged `after 4 up to reach the top`. The claim in the comment above this
+  // loop — that the top is "reached and left alone rather than pulled past" —
+  // was describing an intention the code did not implement.
+  //
+  // So the confirming gesture is a deliberate 60pt nudge instead. It still
+  // moves a page with anywhere left to go, which is the entire job, and it does
+  // not overscroll far enough to refresh when there is not.
+  let upSteps = 0;
+  let upStalls = 0;
+  let atTop = step.from === 'here';
+  if (!atTop) {
+    let last = await sectionHere(deviceQuery, options);
+    for (let i = 0; i < limit; i += 1) {
+      await scrollOne(deviceQuery, udid, 'up', ctx, upStalls ? { spanPt: TOP_CONFIRM_PT } : undefined);
+      const now = await sectionHere(deviceQuery, options);
+      upSteps += 1;
+      // Measured, not inferred from labels: an `up` that moves nothing means we
+      // are at the top.
+      if (scrollDelta(last, now).moved === false) {
+        upStalls += 1;
+        if (upStalls >= 2) { atTop = true; break; }
+      } else {
+        upStalls = 0;
+      }
+      last = now;
+    }
+  }
+
+  const seen = new Map();
+  const filled = [];
+  const sections = [];
+  const travelled = [];
+  let atBottom = false;
+  let section = 0;
+
+  // One read per section, and the bottom is detected at the *start* of the next
+  // iteration rather than at the end of this one. That ordering is what makes
+  // every screenful — including the last — get merged and filled: an earlier
+  // version measured movement after scrolling and broke before reading, which
+  // silently discarded the final section.
+  let prev = null;
+  let stalls = 0;
+  for (; section < limit; section += 1) {
+    const here = await sectionHere(deviceQuery, options);
+    if (prev) {
+      const delta = scrollDelta(prev, here);
+      // Two consecutive stalls, not one.
+      //
+      // A single stall reading is not the bottom, and acting on one is why a
+      // sweep kept jumping from the top straight to the end and never reading
+      // the form in between: any sticky element inside the page — a heading
+      // that stays put, a floating widget — makes one median read as zero. The
+      // operator's diagnosis was exactly this: *"I feel like you miss the form,
+      // you either scroll to the end or to the beginning."*
+      //
+      // Coverage beats stopping early. A wasted section costs about a second; a
+      // missed section costs the whole point of sweeping.
+      if (delta.moved === false) {
+        stalls += 1;
+        if (stalls >= 2) { atBottom = true; break; }
+      } else {
+        stalls = 0;
+      }
+      if (delta.px != null) travelled.push(delta.px);
+    }
+
+    const fresh = here.filter((r) => !seen.has(sweepKey(r)));
+    for (const r of here) if (!seen.has(sweepKey(r))) seen.set(sweepKey(r), { ...r, section: section + 1 });
+    sections.push({ section: section + 1, elements: here.length, fresh: fresh.length });
+
+    // Anything to fill in this section? Do it here, while it is on screen —
+    // which is the whole reason this beats finding a field and then trying to
+    // scroll back to it.
+    if (fill) {
+      for (const [label, text] of Object.entries(fill)) {
+        if (!here.some((r) => alnum(r.label).includes(alnum(label)))) continue;
+        try {
+          await runStep(deviceQuery, udid, {
+            action: step.paste === false ? 'type' : 'paste', into: label, text: String(text),
+          }, ctx);
+          filled.push(`${JSON.stringify(label)} in section ${section + 1}`);
+        } catch (err) {
+          filled.push(`${JSON.stringify(label)} FAILED in section ${section + 1}: ${err.message.split('\n')[0].slice(0, 90)}`);
+        }
+        delete fill[label];
+      }
+    }
+
+    if (wanted && [...seen.values()].some((r) => alnum(r.label).includes(alnum(wanted)))) break;
+    if (fill && !Object.keys(fill).length) break;
+    prev = here;
+    await scrollOne(deviceQuery, udid, 'down', ctx);
+  }
+
+  const all = [...seen.values()];
+  ctx.sweep = all;
+  const hits = wanted ? all.filter((r) => alnum(r.label).includes(alnum(wanted))) : [];
+  const listed = (wanted ? hits : all).slice(0, 30)
+    .map((r) => `[${r.section}] ${JSON.stringify(String(r.label).slice(0, 36))} @${r.x},${r.y}`);
+  const unfilled = fill ? Object.keys(fill) : [];
+  return `swept ${sections.length} section(s)`
+    + `${upSteps ? ` after ${upSteps} up to reach the ${atTop ? 'top' : 'start'}` : ''}`
+    + `${atBottom ? ', reached the bottom' : ', budget spent before the bottom'}`
+    + `${travelled.length ? ` (each gesture moved ${travelled.map((t) => Math.abs(t)).join(', ')}pt)` : ''};`
+    + ` ${all.length} distinct element(s)`
+    + (filled.length ? `; filled ${filled.join(', ')}` : '')
+    + (unfilled.length ? `; NOT FOUND anywhere: ${unfilled.map((u) => JSON.stringify(u)).join(', ')}` : '')
+    + (wanted ? `; ${hits.length} match ${JSON.stringify(wanted)}` : '')
+    + (listed.length ? `: ${listed.join(', ')}` : '');
+}
+
 async function runStep(deviceQuery, udid, step, ctx) {
   switch (step.action) {
     case 'tap': {
@@ -601,7 +2052,8 @@ async function runStep(deviceQuery, udid, step, ctx) {
       // Screen memory first: a familiar screen needs no tree read and no OCR.
       const found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh });
       await input.tapPoint(udid, found.target.x, found.target.y, { durationMs: step.durationMs });
-      return `tapped "${found.target.label}" at ${found.target.x},${found.target.y} (${found.from}${found.from === 'memory' ? ` d=${found.distance}` : ''}, via ${found.target.source})`;
+      return `tapped "${found.target.label}" at ${found.target.x},${found.target.y} (${found.from}${found.from === 'memory' ? ` d=${found.distance}` : ''}, via ${found.target.source})`
+        + relabelledNote(found);
     }
     case 'tapAt': {
       const geo = await ctx.screen();
@@ -618,14 +2070,62 @@ async function runStep(deviceQuery, udid, step, ctx) {
       await input.tapPoint(udid, x, y, { durationMs: step.durationMs });
       return `tapped ${x},${y}`;
     }
+    case 'clear': {
+      // Empty a field. Item 61's oldest half: re-typing appends, and there was
+      // no way to empty anything — not in simframe, and not in XCUITest, Appium
+      // or idb either, none of which has a clear primitive. Command-A then
+      // Delete over HID is the standard answer, and it is layout-independent
+      // because all three are key positions rather than glyphs.
+      const field = await focusField(deviceQuery, udid, { ...step, into: goalOf(step) }, ctx);
+      await input.clearField(udid);
+      // Verified the same way a write is, and with the same rule: OCR may
+      // confirm, never deny. An empty field reads as absence of text, which is
+      // exactly what a sensor that cannot see the field also reports — so only
+      // the tree's own empty-valued control counts as proof it worked.
+      const seen = await fieldContents(deviceQuery, field.found.target, '', ctx);
+      const emptied = seen && seen.landed === false && String(seen.value) === '';
+      return `cleared ${field.where}${emptied ? ' = ""' : ' [unconfirmed — nothing reads back this field\'s contents]'}`;
+    }
     case 'type': {
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
-        await input.typeText(udid, step.text ?? step.value);
-        return `typed into ${field.where}${field.quiet}${field.waited}`;
+        // Replace rather than append, when asked. The field is already focused,
+        // so this costs two key events and no extra resolution.
+        if (step.clear) await input.clearField(udid);
+        // With `into` present, `value` is the *selector*, not the text.
+        //
+        // Reported as `typed into "Asset*" … = "Asset*"` — the field's own
+        // label read back as its contents, because `step.text ?? step.value`
+        // fell through to the selector when no text was given. That is not a
+        // reporting quirk: it means the selector was typed into the field.
+        const sent = textToSend(step);
+        await input.typeText(udid, sent);
+        let back = readbackNote(sent, await fieldContents(deviceQuery, field.found.target, sent, ctx));
+        // Verifying the outcome instead of the precondition puts the race where
+        // it actually shows up. If the keystrokes arrived before the field had
+        // focus they are simply gone — one local retry costs about 200ms, and
+        // throwing here cost an aborted batch and a model round trip.
+        if (back.empty) {
+          await input.tapPoint(udid, field.found.target.x, field.found.target.y);
+          await input.typeText(udid, sent);
+          back = readbackNote(sent, await fieldContents(deviceQuery, field.found.target, sent, ctx));
+          if (back.empty) {
+            throw new Error(
+              `typed into ${field.where} twice and the field still reads empty — the text is not landing.`
+              + ' paste is more reliable than type on this path; keys sends literal characters, not named keys.',
+            );
+          }
+          journalWrite(udid, step, sent, back, ctx);
+          return `typed into ${field.where}${back.note} [took two attempts; the first keystrokes did not land]`;
+        }
+        journalWrite(udid, step, sent, back, ctx);
+        return `typed into ${field.where}${back.note}${back.landed ? '' : field.quiet}`;
       }
       await input.typeText(udid, step.text ?? step.value);
-      return 'typed text';
+      // No selector, so there is nothing to read back — which is a fine trade
+      // for typing into whatever Safari's own form chevrons focused, but it
+      // must not be reported as though the text was seen to land.
+      return 'typed text [unconfirmed — no field named, so nothing was read back]';
     }
     case 'paste': {
       // Long strings are much faster on the pasteboard than through the
@@ -634,11 +2134,22 @@ async function runStep(deviceQuery, udid, step, ctx) {
       // report success anyway.
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
-        await input.pasteText(udid, step.text ?? step.value);
-        return `pasted into ${field.where}${field.quiet}${field.waited}`;
+        const sent = textToSend(step);
+        if (step.clear) await input.clearField(udid);
+        await input.pasteText(udid, sent);
+        const seen = await fieldContents(deviceQuery, field.found.target, sent, ctx);
+        const back = readbackNote(sent, seen);
+        if (back.empty) {
+          throw new Error(
+            `pasted into ${field.where} and the field reads empty — the text did not land.`
+            + ' A first paste can raise the system paste-consent dialog and lose the text; dismiss it and retry.',
+          );
+        }
+        journalWrite(udid, step, sent, back, ctx);
+        return `pasted into ${field.where}${back.note}${back.landed ? '' : field.quiet}`;
       }
       await input.pasteText(udid, step.text ?? step.value);
-      return 'pasted into the focused field';
+      return 'pasted into the focused field [unconfirmed — no field named, so nothing was read back]';
     }
     case 'swipe': {
       const from = { x: step.from?.[0] ?? step.from?.x, y: step.from?.[1] ?? step.from?.y };
@@ -695,6 +2206,10 @@ async function runStep(deviceQuery, udid, step, ctx) {
       const r = await intent.chooseAny(udid, { prefer: step.value ?? step.prefer, geo });
       return `chose "${r.label}" of ${r.optionCount} options`;
     }
+    case 'sweep':
+      return sweep(deviceQuery, udid, step, ctx);
+    case 'seek':
+      return seek(deviceQuery, udid, step, ctx);
     case 'settle': {
       const w = await api.waitFor(deviceQuery, {
         mode: step.mode ?? 'stable',
@@ -747,18 +2262,82 @@ async function runStep(deviceQuery, udid, step, ctx) {
     // about it.
     case 'scrollTo': {
       const query = step.value ?? step.target ?? step.label;
-      const dir = String(step.direction ?? 'down').toLowerCase();
+      // Which way, and it now reads the answer instead of assuming it.
+      //
+      // Reported three times in one round and the most expensive single defect
+      // across five runs: the target sat at **y = −693**, above the viewport,
+      // and this scrolled *down* six times — moving away on every iteration,
+      // with the offset printed in its own error each time — then advised the
+      // tool it already is. The operator watching called it "scrolled too much
+      // and trying to scroll more like a loop", which is exactly what it was.
+      //
+      // The tree knows where the element is whenever it is in the tree at all,
+      // so ask before each gesture and follow the sign. An explicit
+      // `direction` still wins, for a caller who knows better.
+      const asked = step.direction ? String(step.direction).toLowerCase() : null;
       const max = Math.min(MAX_SCROLLS, step.maxScrolls ?? 6);
+      let dir = asked ?? 'down';
+      let reversed = false;
+      // Where the target is, when the tree knows. `null` means no evidence, and
+      // that distinction is load bearing: guessing "up" without it scrolls to
+      // the top of a web page, which **triggers pull-to-refresh**, reloads the
+      // page and changes the screen hash — defeating the end-detection below
+      // and reading, from outside, as an endless loop. Observed live.
+      const offsetSays = async () => {
+        if (asked) return asked;
+        try {
+          const { entry, points } = await api.readScreenWith(deviceQuery, { useOcr: false, options: ctx.options });
+          const hit = matching.resolve(entry.targets ?? [], String(query));
+          const y = hit?.target?.y;
+          if (!Number.isFinite(y)) return null;
+          if (y < 0) return 'up';
+          if (y > (points?.height ?? Infinity)) return 'down';
+          return dir;
+        } catch {
+          return null;
+        }
+      };
       for (let i = 0; i <= max; i += 1) {
         try {
           const found = await api.locate(deviceQuery, query, { index: step.index, refresh: i > 0 });
           return `"${found.target.label}" is in view at ${found.target.x},${found.target.y}` +
-            (i ? ` after ${i} scroll${i === 1 ? '' : 's'}` : ' already');
+            (i ? ` after ${i} scroll${i === 1 ? '' : 's'} ${dir}` : ' already');
         } catch (err) {
-          if (i === max) throw new Error(`scrolled ${dir} ${max}x without finding ${query}: ${err.message}`);
+          if (i === max) {
+            throw new Error(`scrolled ${dir} ${max}x without finding ${query}: ${err.message}`);
+          }
         }
+        const evidence = await offsetSays();
+        if (evidence) dir = evidence;
+        const wasAt = await hashNow(deviceQuery, ctx.options);
         await runStep(deviceQuery, udid, { action: 'scroll', value: dir }, ctx);
-        await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 250, timeoutMs: 2500, options: ctx.options });
+        // A scroll either moves immediately or not at all, so it does not need a
+        // transition's budget. Six iterations at 2,500ms was most of why this
+        // read as a loop from outside — *"it looks like a loop"* — rather than
+        // as a search.
+        await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 200, timeoutMs: SCROLL_SETTLE_MS, options: ctx.options });
+        // A scroll that moved nothing means we are against an end. Burning the
+        // rest of the budget against it is what the operator watched happen:
+        // *"your scroll still looks unstable, you're just scrolling past the
+        // page"*. Reverse once — the target may be behind us, and on a page
+        // whose fields never enter the tree there is no offset to follow — then
+        // stop rather than thrash.
+        const nowAt = await hashNow(deviceQuery, ctx.options);
+        if (wasAt && nowAt && wasAt === nowAt) {
+          // Reverse only on evidence. Without it we do not know the target is
+          // behind us, and scrolling blindly the other way is how a web page
+          // gets pulled to refresh.
+          if (reversed || !evidence) {
+            throw new Error(
+              `${query} is not reachable by scrolling: ${dir} stopped moving after ${i + 1} attempt(s)`
+              + (evidence ? ' and so did the other way.' : ' and the tree does not say where it is,'
+                + ' so there is no direction to try.')
+              + ' It may not be in the accessibility tree at all — read the screen, or aim at a coordinate.',
+            );
+          }
+          reversed = true;
+          dir = dir === 'down' ? 'up' : 'down';
+        }
       }
       throw new Error(`could not bring ${query} into view`);
     }
@@ -766,9 +2345,45 @@ async function runStep(deviceQuery, udid, step, ctx) {
     // Wait for a selector rather than a label, so it works on screens the
     // accessibility tree never described.
     case 'waitFor': {
+      // One string, or any of several.
+      //
+      // Reported: a wait on *"any login or dashboard content"* spent **120
+      // seconds** while the login screen was already there — and the failure
+      // message itself listed `Email`, `Password`, `Remember me`. A phrase like
+      // that is a disjunction, and resolving it as one intent asks the matcher
+      // for something no single element answers.
+      //
+      // `{"waitFor": {"any": ["Email", "Dashboard"]}}` says it directly, and
+      // the first to appear wins. Which is also the honest division of labour:
+      // simframe resolves an intent to an element, and *which of several
+      // outcomes am I waiting for* is the caller's question to phrase.
+      const alternatives = Array.isArray(step.any) ? step.any.filter(Boolean).map(String) : null;
       const query = step.value ?? step.target ?? step.text;
+      if (!alternatives && !query) throw new Error('usage: {"waitFor": "text"} or {"waitFor": {"any": ["a", "b"]}}');
       const limit = Date.now() + (step.timeoutMs ?? 8000);
       let lastError = 'never appeared';
+      if (alternatives) {
+        for (let attempt = 0; ; attempt += 1) {
+          for (const one of alternatives) {
+            try {
+              const found = await api.locate(deviceQuery, one, { refresh: attempt > 0 });
+              return `${JSON.stringify(one)} appeared at ${found.target.x},${found.target.y}`
+                + ` (first of ${alternatives.length} awaited)`;
+            } catch (err) {
+              lastError = err.message;
+            }
+          }
+          if (Date.now() >= limit) {
+            throw new Error(
+              `none of ${alternatives.length} awaited strings appeared`
+              + ` (${alternatives.map((a) => JSON.stringify(a)).join(', ')}) in ${step.timeoutMs ?? 8000}ms.`
+              + ` Last: ${lastError}`,
+            );
+          }
+          await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 200, timeoutMs: 700, options: ctx.options })
+            .catch(() => null);
+        }
+      }
       for (let attempt = 0; ; attempt += 1) {
         try {
           const found = await api.locate(deviceQuery, query, { index: step.index, refresh: attempt > 0 });
@@ -806,11 +2421,44 @@ async function runStep(deviceQuery, udid, step, ctx) {
       const want = String(step.is ?? (step.gone ? 'gone' : 'visible')).toLowerCase();
       let found = null;
       try {
-        found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh });
+        // Fresh by default, and this was the single most expensive finding in a
+        // reported round. `assert REVIEW is enabled` failed while the map
+        // printed by that very call showed the button enabled three lines
+        // below: the assert had resolved against screen *memory*, and state
+        // changes without a screen's identity changing.
+        //
+        // A verification step reading a cached map is self-defeating. It costs
+        // one perception pass, which is the same trade Phase 11.5 made for the
+        // trailing map and for the same reason — a read is cheaper than the
+        // round trip a wrong verdict causes.
+        //
+        // The reporter's framing is why this is worth a paragraph: *"I put an
+        // assert in to be careful, and being careful is what broke the flow.
+        // The lesson an agent learns is 'do not assert inside batches', which
+        // is the opposite of what you want learned."*
+        found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
       } catch (err) {
         if (want === 'gone') return `${query} is gone`;
         throw new Error(`${query}: ${err.message}`);
       }
+      // A state that disagrees earns one more look, because the state may have
+      // arrived between the action and the assert — which is exactly what a
+      // batch does. `tap` already re-takes a stale baseline and says so.
+      const disagrees = (t) => (want === 'enabled' && t.enabled === false)
+        || (want === 'disabled' && t.enabled !== false);
+      let retook = '';
+      if (disagrees(found.target)) {
+        await api.waitFor(deviceQuery, {
+          mode: 'settle', stableMs: 250, timeoutMs: ASSERT_RETAKE_MS, options: ctx.options,
+        }).catch(() => null);
+        try {
+          const again = await api.locate(deviceQuery, query, { index: step.index, refresh: true, options: ctx.options });
+          if (!disagrees(again.target)) {
+            found = again;
+            retook = ' [state arrived between the action and the assert; re-read from the live screen]';
+          }
+        } catch { /* keep the first reading and report it */ }
+      }
       const t = found.target;
       switch (want) {
         case 'visible':
@@ -818,11 +2466,11 @@ async function runStep(deviceQuery, udid, step, ctx) {
         case 'gone':
           throw new Error(`${query} is still on screen at ${t.x},${t.y}`);
         case 'enabled':
-          if (t.enabled === false) throw new Error(`"${t.label}" is disabled`);
-          return `"${t.label}" is enabled`;
+          if (t.enabled === false) throw new Error(`"${t.label}" is disabled, and still disabled on a second look`);
+          return `"${t.label}" is enabled${retook}`;
         case 'disabled':
-          if (t.enabled !== false) throw new Error(`"${t.label}" is not disabled`);
-          return `"${t.label}" is disabled`;
+          if (t.enabled !== false) throw new Error(`"${t.label}" is not disabled, on two looks`);
+          return `"${t.label}" is disabled${retook}`;
         case 'value': {
           const expected = String(step.equals ?? step.text ?? '');
           const actual = [t.label, t.value, ...(t.aliases ?? [])].filter(Boolean).join(' ');