simframe 0.12.1 → 0.13.0

package/src/index.js

@@ -13,6 +13,7 @@ import {
   isBlackFrame,
   maxCellDelta,
   CELL_CHANGE,
+  describeMotion,
   regionDeltas,
   regionMap,
   signatureDiff,
@@ -110,6 +111,48 @@ async function deviceGeometry(udid, state) {
   };
 }
 
+/**
+ * How long to wait for a daemon to exist at all. A first build is slower than a
+ * spawn, which is what this number is sized for.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+
+/**
+ * How long to keep waiting once the daemon is demonstrably alive.
+ *
+ * Sized from the measurement that caused it: a hosted runner's simulator took
+ * roughly 27 s to produce its first frame while the daemon reported a healthy
+ * 75 ms median. Three times the ordinary budget, and still bounded.
+ */
+export const LIVE_DAEMON_CAP_MS = 60_000;
+
+/**
+ * How many gestures may land on a motionless screen before that is evidence.
+ *
+ * **This replaces a duration threshold, and the replacement is the point.** The
+ * first version asked "has the screen been still for a long time?" and needed
+ * 20 s before it would speak. A field report then caught a frame roughly three
+ * hours stale, presented as 130 ms old, on a screen still for **8.2 seconds** —
+ * so the check sat silently under its own gate during exactly the failure it
+ * was written for. A threshold chosen from one earlier example is not a
+ * mechanism.
+ *
+ * What says "dead surface" is not how long the screen has been quiet. It is
+ * that we kept touching it and *nothing moved at all*. One tap that changes
+ * nothing is ordinary — a disabled control, a form refusing a submit. Three in
+ * a row, with not one pixel of response, is a different claim.
+ */
+export const SURFACE_SUSPECT_INPUTS = 3;
+
+/**
+ * Slack between "input landed" and "the screen should have moved".
+ *
+ * A gesture only counts against the surface if it landed *inside* the quiet
+ * period with room to spare — otherwise the tap that ends the quiet period
+ * counts as evidence against it.
+ */
+export const SURFACE_MARGIN_MS = 400;
+
 export function daemonStatus(udid) {
   const meta = store.readJson(store.paths(udid).meta);
   const pid = meta?.pid ?? null;
@@ -134,10 +177,13 @@ export async function ensureDaemon(deviceQuery, options = {}) {
   // A dead daemon leaves its last state.json behind. Anything captured before
   // we (re)started the loop is not evidence of a live screen, so ignore it.
   const minCapturedAt = existing.alive ? 0 : Date.now();
+  // The pid we spawned, which is the only honest answer to "did a daemon come
+  // up" — see the comment on the wait below.
+  let spawnedPid = null;
   if (!existing.alive) {
     if (acquireSpawnLock(p.lock)) {
       try {
-        await startEngine(device.udid, options);
+        spawnedPid = (await startEngine(device.udid, options)).pid;
       } finally {
         // Hold the lock briefly so a burst of callers does not double-spawn.
         setTimeout(() => releaseSpawnLock(p.lock), 1500).unref?.();
@@ -146,16 +192,79 @@ export async function ensureDaemon(deviceQuery, options = {}) {
   }
 
   // The daemon may need a first build, which is slower than a spawn.
-  const deadline = Date.now() + (options.readyTimeoutMs ?? 20_000);
-  while (Date.now() < deadline) {
+  const deadline = Date.now() + (options.readyTimeoutMs ?? READY_TIMEOUT_MS);
+  // A live daemon that has not rendered yet is not a failed daemon.
+  //
+  // Measured on a hosted runner: `simframe start` gave up, and the daemon's own
+  // log — captured by the on-failure step eight seconds later — showed
+  // `frame=#1 age=1514ms, 1.0 fps, median 75.08ms`. It was working. The
+  // simulator's display had simply taken about 27 s to produce anything on a
+  // loaded build farm, against a 20 s budget measured on a developer's machine.
+  // Aborting there fails an entire run over a device that was about to work.
+  //
+  // So the budget applies to *getting a daemon*; once we have a live one, the
+  // wait extends to a hard cap. The cap still exists, because a daemon that is
+  // alive and never renders is a real failure and has to be reportable — but it
+  // is now a different sentence from a daemon that never started, and those two
+  // had read identically, which cost a log dive to tell apart.
+  const liveDeadline = Date.now() + LIVE_DAEMON_CAP_MS;
+  let sawLiveDaemon = false;
+  let sawProcess = false;
+  for (;;) {
     const state = store.readJson(p.state);
     if (state && state.capturedAt >= minCapturedAt && Date.now() - state.capturedAt < 30_000) {
       return { device, state, started: !existing.alive };
     }
+    // Two different questions, and for a long time one file answered both.
+    //
+    // `daemonStatus` reads meta.json, which the daemon writes in `claim()` —
+    // *after* `platform.attach`, its slowest startup step. So a daemon that has
+    // spawned and is attaching to CoreSimulator is indistinguishable, from
+    // here, from one that never started: both are `alive: false`. That is the
+    // condition the live cap below exists for, and it could never be reached in
+    // the case that produced it, because reaching it required the very file
+    // whose absence was the problem.
+    //
+    // Measured on a hosted runner, 2026-09-13: `simframe start` gave up after
+    // 20 s saying **"no daemon process came up"**, and the next step of the
+    // same job printed `● iPhone 16 Pro pid=9573 frame=#5 age=652ms` with a
+    // daemon log showing it had been capturing the whole time. The sentence was
+    // not merely unhelpful, it named the wrong condition — the fourth time this
+    // project has failed that way and the second time in two days.
+    //
+    // The pid we spawned is the honest signal and it was already in hand;
+    // `startEngine` was discarding it.
+    const claimed = daemonStatus(device.udid).alive;
+    const running = claimed || (spawnedPid != null && store.isProcessAlive(spawnedPid));
+    sawLiveDaemon = sawLiveDaemon || claimed;
+    sawProcess = sawProcess || running;
+    if (Date.now() >= (running ? liveDeadline : deadline)) break;
     await sleep(80);
   }
   const tail = readLogTail(p.log);
-  throw new Error(`simframe daemon did not produce a frame for ${device.name}${tail ? `\n${tail}` : ''}`);
+  throw new Error(
+    `simframe daemon did not produce a frame for ${device.name} — `
+    + `${readinessFailure({ sawLiveDaemon, sawProcess })}${tail ? `\n${tail}` : ''}`,
+  );
+}
+
+/**
+ * Which of three failures this was.
+ *
+ * Extracted so it can be tested, for the reason `screenshotFailure` was: the
+ * whole defect here is a message naming the wrong condition, and a message is
+ * only checkable if something can ask for it without a device. Two of these
+ * three sentences did not exist until a runner produced each of them in turn and
+ * both arrived reading as the third.
+ */
+export function readinessFailure({ sawLiveDaemon, sawProcess }) {
+  const cap = Math.round(LIVE_DAEMON_CAP_MS / 1000);
+  if (sawLiveDaemon) return `the daemon is running and the display produced no frame in ${cap}s`;
+  if (sawProcess) {
+    return `the daemon process started but never claimed the device in ${cap}s`
+      + ' — it is stuck attaching to the simulator rather than failing to launch';
+  }
+  return 'no daemon process came up';
 }
 
 /** Why the daemon was not used, when it was not. Surfaced by doctor. */
@@ -213,14 +322,16 @@ async function startEngine(udid, options) {
     if (built.ok) {
       engineFallbackReason = null;
       recordFallback(udid, null);
-      engine.spawnDaemon(udid, options);
-      return 'simframed';
+      // The pid, not just the name. Whether a daemon came up is a question
+      // about a process, and answering it from meta.json — which the daemon
+      // writes only after attaching — could not tell "never started" from
+      // "still starting". See the wait in `ensureDaemon`.
+      return { engine: 'simframed', pid: engine.spawnDaemon(udid, options)?.pid ?? null };
     }
     engineFallbackReason = built.reason ?? 'simframed unavailable';
     recordFallback(udid, engineFallbackReason);
   }
-  spawnNodeDaemon(udid, options);
-  return 'screenshot';
+  return { engine: 'screenshot', pid: spawnNodeDaemon(udid, options)?.pid ?? null };
 }
 
 function spawnNodeDaemon(udid, options) {
@@ -244,6 +355,7 @@ function spawnNodeDaemon(udid, options) {
     env: process.env,
   });
   child.unref();
+  return child;
 }
 
 function acquireSpawnLock(lockFile) {
@@ -384,6 +496,49 @@ export function liveness(udid, state) {
   if (!damageDriven && ageMs > STALE_FRAME_MS) {
     return { ok: false, ageMs, stalled: false, note: `capture loop is stalled: newest frame is ${ageMs}ms old` };
   }
+
+  // A live loop re-reading a dead surface, which every other signal calls fine.
+  //
+  // Reported from the field on 0.12.2, and it is the most expensive shape this
+  // tool has produced: `sim_look` served the *login screen* for three minutes
+  // while the app was four screens deep in a wizard, and announced the frame as
+  // 66ms old. The daemon was not lying — the frame really was new. It was a new
+  // read of a surface that had stopped updating. Every check above passes: the
+  // process is alive, no read failed, the age is tiny.
+  //
+  // The contradiction is between two numbers we already have. `stableForMs`
+  // says the screen has not changed in N ms; `lastInputAt` says we were
+  // delivering taps and swipes during that window. A screen that has not moved
+  // since *before* we last touched it, for long enough that several gestures
+  // landed inside the quiet period, is not a calm screen. The tester's own
+  // figures: stable for 159,753 ms across three screen transitions.
+  //
+  // Deliberately a WARNING and not a failure. A genuinely inert screen is
+  // possible — a form that rejects every tap, a disabled control tapped twice —
+  // and turning that into a hard error would be a confident wrong answer of
+  // exactly the kind this project keeps paying for. It says what it sees and
+  // names the arbiter.
+  const stableForMs = state?.stableForMs;
+  if (Number.isFinite(stableForMs)) {
+    // The moment the screen last moved. Every gesture delivered after it landed
+    // on a screen that did not react.
+    const lastChange = Date.now() - stableForMs + SURFACE_MARGIN_MS;
+    const ignored = store.inputTimes(udid).filter((t) => t > lastChange);
+    if (ignored.length >= SURFACE_SUSPECT_INPUTS) {
+      const quiet = Math.round(stableForMs / 1000);
+      return {
+        ok: true,
+        ageMs,
+        stalled: false,
+        suspectSurface: true,
+        ignoredInputs: ignored.length,
+        note: `${ignored.length} gestures have been delivered without the screen moving at all `
+          + `(still for ${quiet < 1 ? `${Math.round(stableForMs)}ms` : `${quiet}s`}), `
+          + 'so the frames are new and the surface behind them may be dead. '
+          + 'The accessibility tree is read separately and is the tiebreaker; `simframe revive` re-attaches capture.',
+      };
+    }
+  }
   return { ok: true, ageMs, stalled: false, note: null };
 }
 
@@ -709,6 +864,37 @@ function timingOfNow(udid, state) {
  * sampled after the fact is the single most common way to wait for a change
  * that has already happened.
  */
+/**
+ * How far back "still moving" looks, in milliseconds.
+ *
+ * **In time, not in frames**, and that distinction is the whole of it. The
+ * first version kept the last eight frame pairs, on the reasoning that at a
+ * 60 ms poll floor eight frames is about half a second. Frames are not a clock:
+ * capture is damage-driven with a slow idle floor, so on a quiet screen eight
+ * frames spanned *sixteen seconds* — and the window still held the transition
+ * that had brought us to the screen. A home screen with one animated widget
+ * duly reported movement in all thirty-two regions.
+ *
+ * One second, long enough that a stepping animation is not missed between two
+ * frames and short enough that the entry transition is gone by the time a
+ * settle gives up.
+ */
+export const MOTION_WINDOW_MS = 1000;
+
+/**
+ * How young a frame has to be to count as "the screen right now".
+ *
+ * The daemon's idle floor is 2,000 ms — on a screen with no damage it captures
+ * anyway, at that cadence, precisely so state stays fresh enough to reason
+ * about. So a frame younger than that floor plus a margin is the current
+ * screen; older than it means the loop has missed its own beat, which is what
+ * `liveness` is for.
+ *
+ * Tied to the daemon's floor rather than chosen, because a number chosen here
+ * would drift away from it silently the first time the floor moved.
+ */
+export const FRAME_IS_CURRENT_MS = 2500;
+
 export async function waitFor(
   deviceQuery,
   { mode = 'settle', since, stableMs = 600, timeoutMs = 8000, reactionMs = 2500, baselineHash, options } = {},
@@ -750,6 +936,29 @@ export async function waitFor(
     ? hexToSignature(resolved.entry.sig)
     : (requested == null ? hexToSignature(currentSig(first) ?? '') : null);
   let smallChange = false;
+  /**
+   * Where the screen moved while we waited — item 123.
+   *
+   * The per-region maximum over a trailing window of frame pairs, so a settle
+   * that gives up can say *where* rather than only that it did.
+   *
+   * A window and not a running max over the whole wait, which is what the first
+   * version did and it was useless: every wait begins with the transition that
+   * brought us here, so a home screen with one animated widget reported
+   * movement in all thirty-two regions and "spread across the screen". The
+   * question a settle failure asks is *what is still moving*, not what has
+   * moved at any point since we started looking.
+   *
+   * A window rather than the last pair alone, because a blinking or stepping
+   * animation is between frames as often as not, and a single pair would
+   * report a still screen that is not one.
+   *
+   * Costs one subtraction per region per frame over a signature that was
+   * already read and parsed for `smallChange`.
+   */
+  const motionRing = [];
+  let motionPrev = null;
+  let motionSeq = null;
   /** Frames the display was not rendering at all. See `isBlackFrame`. */
   let blackFrames = 0;
   let blackSinceStart = null;
@@ -795,6 +1004,46 @@ export async function waitFor(
     sawChange = false;
   }
 
+  /**
+   * What the daemon says is animating, if anything — and it has always known.
+   *
+   * `Motion.state` in the daemon localises a small persistent animation and
+   * publishes it as `motion.animating`, a bounding box, alongside its own
+   * `settled` flag. Nothing in JavaScript read either. `waitFor` decided
+   * stillness from `stableForMs` alone, which is derived from a *mean* over the
+   * grid, and a spinner does not move a mean.
+   *
+   * Measured on the testbed's Diagnostics screen, which now carries one on
+   * purpose: frames arriving every 85 ms, `motion.animating` boxed at 13x13,
+   * `motion.settled` **false** — and `stableForMs` **79,207**. Seventy-nine
+   * seconds of claimed stillness on a screen that had never once stopped. A
+   * field report had already called this in as `settled after 62ms` on a
+   * still-loading screen.
+   *
+   * Deliberately reported and **not** acted on. Requiring the daemon's `settled`
+   * here would be correct for a spinner and wrong for a text caret, which is
+   * also small, also persistent, and must never stop a screen from settling —
+   * and choosing between them needs a caret measured, not a threshold picked
+   * today. So the disagreement becomes visible instead of being resolved by
+   * guess: the caller is told a part of the screen is still moving and where,
+   * and can decide. The decision is an open item with a number attached to it.
+   */
+  const animatingNow = () => {
+    const box = last?.motion?.animating;
+    if (!box) return null;
+    return { ...box, daemonSettled: last.motion.settled === true };
+  };
+
+  /** The last second of movement, collapsed to one per-region maximum. */
+  function motionSummary() {
+    const cutoff = Date.now() - MOTION_WINDOW_MS;
+    const recent = motionRing.filter((e) => e.at >= cutoff);
+    if (!recent.length) return null;
+    const max = recent[0].deltas.map((_, i) => Math.max(...recent.map((e) => e.deltas[i] ?? 0)));
+    if (!max.some((d) => d > 0)) return null;
+    return { deltas: max, map: regionMap(max), windowMs: MOTION_WINDOW_MS, ...describeMotion(max) };
+  }
+
   const done = (satisfied, extra = {}) => ({
     device,
     state: last,
@@ -812,6 +1061,24 @@ export async function waitFor(
     // because the app drew black. What makes it the capture wedge is that it
     // stays black while input is being delivered, and the caller knows that.
     blackMs: blackSinceStart ? Date.now() - blackSinceStart : 0,
+    // Only worth carrying when something actually moved; a still screen that
+    // never satisfied the wait has nothing to point at.
+    motion: motionSummary(),
+    animating: animatingNow(),
+    /**
+     * Everything that decided this answer, for the failure message.
+     *
+     * Two CI cycles were spent guessing at a `screen did not settle within
+     * 25008ms` — a sentence that names the one number which is never the
+     * reason. The wait turns on three things and the log carried none of them:
+     * how long the screen had actually been still, how much stillness was
+     * being asked for, and whether any frame arrived at all. "Still for 1,200
+     * of the 1,400 ms required" and "still for 135,000 ms and nothing arrived"
+     * are opposite diagnoses and they had one sentence between them.
+     */
+    stillForMs: Number.isFinite(last?.stableForMs) ? last.stableForMs : null,
+    stableMsRequired: stableMs,
+    framesSeen: Number.isFinite(last?.seq) ? last.seq - startSeq : null,
     baselineHash: baselineHashValue,
     baselineResolved,
     waitedMs: Date.now() - startedAt,
@@ -865,6 +1132,23 @@ export async function waitFor(
         }
       }
 
+      // Track where it is moving, on new frames only — comparing a frame with
+      // itself is a row of zeros that would dilute nothing but waste the work.
+      if (state.seq !== motionSeq) {
+        const sigHex = currentSig(state);
+        const sig = sigHex ? hexToSignature(sigHex) : null;
+        if (sig) {
+          if (motionPrev) {
+            motionRing.push({ at: Date.now(), deltas: regionDeltas(sig, motionPrev) });
+            // Bounded in time by the summary and in length here, so a screen
+            // rendering at 60 fps for ten seconds cannot grow this without end.
+            while (motionRing.length > 240) motionRing.shift();
+          }
+          motionPrev = sig;
+        }
+        motionSeq = state.seq;
+      }
+
       // A pause that turned out not to be the end of the transition. Only
       // pauses followed by more movement count: the quiet at the end of a
       // settle is the answer, not a gap.
@@ -900,10 +1184,30 @@ export async function waitFor(
         // the caller acted can never satisfy it; once the change is seen,
         // stableForMs is measured from that change. Plain "stable" has no such
         // requirement — an already-still screen genuinely is stable.
-        // At least one frame must arrive during the call, so the answer is
-        // never derived purely from what was already on disk.
+        //
+        // The evidence must be *current*, and that used to be spelled "at least
+        // one frame must arrive during the call". The intent is right and the
+        // spelling made the wait unsatisfiable on exactly the screens it is
+        // asked about most. Capture is damage-driven: a screen that is not
+        // moving produces no new frame by design, so on a still screen the
+        // condition asks for evidence the system has deliberately chosen not to
+        // generate, and the wait burns its whole budget and reports *"screen did
+        // not settle"* about a screen that has been motionless throughout.
+        //
+        // Measured here rather than argued: a flow step reported `did not settle
+        // within 1547ms` while its own evidence line read **still for 3548ms of
+        // the 1400ms required; NO frame arrived while waiting**. Three and a half
+        // seconds of stillness, two and a half times what was asked, refused.
+        //
+        // So currency is a question about time, not about a counter — the same
+        // correction the motion window needed. A frame younger than the capture
+        // loop's own idle floor *is* the screen as it is now. `liveness` is
+        // checked at the top of every iteration and already rejects a stale file
+        // from a dead daemon, which is the case the counter was really guarding.
         const freshFrames = state.seq - startSeq;
-        if (sawChange && freshFrames >= 1 && state.stableForMs >= stableMs) {
+        const age = Date.now() - (state.capturedAt ?? 0);
+        const current = freshFrames >= 1 || age <= FRAME_IS_CURRENT_MS;
+        if (sawChange && current && state.stableForMs >= stableMs) {
           return done(true);
         }
       }
@@ -1431,7 +1735,28 @@ async function locateWith(
   const target = index != null ? candidates[index] : candidates[0];
   if (!target) {
     const visible = entry.targets.filter((t) => t.label);
-    const sample = visible.slice(0, 12).map((t) => t.label).join(', ');
+    const shown = visible.slice(0, 12).map((t) => t.label);
+    // Say when the list is cut. A field report found `"Work Orders" is not on
+    // this screen. Visible: …` on a screen whose own element map, three lines
+    // below in the same reply, listed `#25 text 200,836 Work Orders` — it was
+    // simply past the twelfth entry. A truncated list that does not announce
+    // its truncation reads as an exhaustive one.
+    const sample = shown.join(', ') + (visible.length > shown.length ? `, …and ${visible.length - shown.length} more` : '');
+    // An index past the end is not an absent element, and reporting it as one
+    // sent a tester looking for a control that was on the screen all along.
+    // `{"tap": "Work Orders", "index": 1}` on a screen with exactly one match
+    // said "not on this screen" while the map listed it.
+    if (index != null && candidates.length) {
+      throw metrics.tag(
+        new Error(
+          `"${query}" matches ${candidates.length} thing${candidates.length === 1 ? '' : 's'} on this screen,`
+          + ` so index ${index} is out of range — valid indices are 0..${candidates.length - 1}.`
+          + ` Nearest: ${candidates.slice(0, 4).map((c) => `[${candidates.indexOf(c)}] ${JSON.stringify(String(c.label ?? '').slice(0, 28))}`).join(', ')}`,
+        ),
+        'ambiguous_intent',
+        { candidates: candidates.slice(0, 8), intent: query, ambiguous: true },
+      );
+    }
     throw metrics.tag(
       new Error(`"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`),
       from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',

package/src/input.js

@@ -623,6 +623,10 @@ export function shouldRebuildSession({ stale, bootedAt }, rebuiltFor) {
 const rebuiltForBoot = new Map();
 export async function ensureFreshSession(udid) {
   if (!udid) return null;
+  // Every input path calls this first, so it is the one place that knows the
+  // hands are about to move. `liveness` needs that timestamp to tell a calm
+  // screen from a dead surface — see `store.noteInput`.
+  store.noteInput(udid);
   const health = await sessionHealth(udid);
   if (!shouldRebuildSession(health, rebuiltForBoot.get(udid))) return null;
   rebuiltForBoot.set(udid, health.bootedAt);

package/src/mcp.js

@@ -459,7 +459,13 @@ function header(device, state, ageMs, extra = '') {
 }
 
 function livenessLine(live) {
-  return live?.ok ? null : `WARNING: ${live.note}`;
+  // `ok` is not the only thing worth saying. A surface that has stopped
+  // updating leaves every hard signal green — the loop is alive, no read
+  // failed, the frame is milliseconds old — and reporting nothing is how
+  // `sim_look` served a three-minute-old login screen while announcing it as
+  // 66ms old. A note that exists must reach the caller.
+  if (live?.note) return `WARNING: ${live.note}`;
+  return null;
 }
 
 function sinceLine(since) {

package/src/metrics.js

@@ -151,7 +151,7 @@ export const readSupervisions = (udid, opts) => readJsonl(metricPaths(udid).supe
  */
 export function recordSupervision(udid, {
   session, index, step, edge, screen, decision, from, reason, ms,
-  stillMs, p95, samples, expect, failure, outcome,
+  stillMs, p95, samples, expect, failure, outcome, supervisor, situation,
 }) {
   // Swallowed rather than thrown, unlike `recordEscalation`'s guard, and the
   // difference is deliberate: this is called from inside a flow's failure
@@ -171,6 +171,19 @@ export function recordSupervision(udid, {
     screen_fingerprint: screen ?? null,
     decision,
     from: from ?? 'model',
+    // *Which* judge, not just that there was one.
+    //
+    // Every arm of the capacity comparison writes to this one log, and without
+    // this field a population collected under Apple and one collected under a
+    // 14B are one undifferentiated file — the comparison the owner asked for
+    // would be unreadable from its own data. `from` says rule-or-model; this
+    // says which model.
+    supervisor: supervisor ?? null,
+    // The question, not only the answer. Without it, asking a second judge
+    // about the same situations means driving the device a second time — which
+    // puts the device's own variance inside a comparison that is about the
+    // judges. Null for a rule-sourced ruling, which never composed one.
+    situation: situation ?? null,
     // Recorded, never presented as the ground for what happened: the supervisor
     // has returned a correct decision with a reason citing a rule that did not
     // apply. Keeping it is how that stays measurable instead of anecdotal.
@@ -287,11 +300,30 @@ const VERIFYING_STEPS = new Set([
  */
 export function reasonForStepError(step, err) {
   const tagged = escalationOf(err);
-  if (tagged) return tagged;
+  if (tagged) return { ...tagged, classified: true };
   const action = step?.action;
-  if (action === 'confirm' || action === 'chooseAny') return { reason: 'novel_dialog', candidates: [], tried: [] };
-  if (VERIFYING_STEPS.has(action)) return { reason: 'verification_failed', candidates: [], tried: [] };
-  return { reason: 'verification_failed', candidates: [], tried: [] };
+  if (action === 'confirm' || action === 'chooseAny') {
+    return { reason: 'novel_dialog', candidates: [], tried: [], classified: true };
+  }
+  // Everything else is a *fallback*, and it now says so.
+  //
+  // This had two branches that returned the same value, which made it look
+  // like it discriminated. It does not: any step that threw without a site
+  // tagging it lands here. In a real field session that was **90% of all
+  // escalations** — and `FACULTY` then reported every one of them as evidence
+  // against "sense of time (Phase 11)", a claim nothing in the record supports.
+  //
+  // The tester's own first call failed with `unknown step "wait_for"` — a typo
+  // — and that too would be filed as evidence about which faculty to build
+  // next. CLAUDE.md calls this log the steering wheel; a steering wheel that
+  // pools typos, inert controls and slow lists into one reason is pointing
+  // somewhere nobody chose.
+  //
+  // No sixth reason: "unknown is not a reason" stays, and a vocabulary that
+  // admits "other" collects a pile of "other". What changes is that the record
+  // carries whether the reason was *read off the failure* or *assumed*, and
+  // the report declines to recommend a faculty for the assumed ones.
+  return { reason: 'verification_failed', candidates: [], tried: [], classified: false };
 }
 
 /**
@@ -312,6 +344,11 @@ export const PLAN_REASONS = {
   'no-route': 'no_plan',
   'unreplayable-edge': 'no_plan',
   'unknown-flow': 'no_plan',
+  // A route that ran and did not land. Not `no_plan`: there *was* a plan and it
+  // was followed — what could not be confirmed is that it worked, which is what
+  // `verification_failed` means everywhere else in this file.
+  'route-halted': 'verification_failed',
+  'arrived-elsewhere': 'verification_failed',
 };
 
 /** A short, bounded description of a candidate element, for the log. */
@@ -422,6 +459,10 @@ export function recordEscalation(udid, {
   modelTurns = 1,
   wallMs = null,
   detail = null,
+  // Was this reason read off the failure, or assumed because nothing said?
+  // Default `false`, so a caller that does not think about it cannot
+  // accidentally claim precision it does not have.
+  classified = false,
 } = {}) {
   if (!REASONS.includes(reason)) throw new Error(`not an escalation reason: ${reason}`);
   if (!OUTCOMES.includes(outcome)) throw new Error(`not an escalation outcome: ${outcome}`);
@@ -437,6 +478,7 @@ export function recordEscalation(udid, {
     // What was asked for, in the caller's words. Ground truth for Phase 17's
     // go/no-go, and on its own it answers "what kind of decision is costing us".
     intent: intent ? String(intent).slice(0, 120) : null,
+    classified: Boolean(classified),
     step_index: stepIndex,
     screen_fingerprint: fingerprint,
     reason,
@@ -617,7 +659,9 @@ export function hpi({ flows, baselines = {} }) {
  */
 export function breakdown(records, { session = null, flow = null } = {}) {
   const byReason = {};
-  for (const r of REASONS) byReason[r] = 0;
+  const classifiedByReason = {};
+  const assumedByReason = {};
+  for (const r of REASONS) { byReason[r] = 0; classifiedByReason[r] = 0; assumedByReason[r] = 0; }
   const byScreen = new Map();
   const byOutcome = {};
   const bySession = new Map();
@@ -641,6 +685,12 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     }
     if (r.flow_name) byFlow.set(r.flow_name, (byFlow.get(r.flow_name) ?? 0) + 1);
     byReason[r.reason] += 1;
+    // Three states, not two. A record written before this field existed makes
+    // no claim either way, and folding it in with "assumed" would make an old
+    // log look like a diagnosis failure — a warning that cries wolf is how a
+    // real one gets ignored, which this file already knows in another place.
+    if (r.classified === true) classifiedByReason[r.reason] += 1;
+    else if (r.classified === false) assumedByReason[r.reason] += 1;
     byOutcome[r.outcome] = (byOutcome[r.outcome] ?? 0) + 1;
     // Already avoided locally, so not avoidable by anything unbuilt.
     if (r.outcome !== 'resolved_locally') avoidable += 1;
@@ -667,9 +717,20 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     pooled: sessions.length > 1 || unattributed > 0,
     by_flow: Object.fromEntries([...byFlow.entries()].sort((a, b) => b[1] - a[1])),
     by_reason: byReason,
+    // How many of each reason were *read off the failure* rather than assumed.
+    //
+    // The breakdown above picks the next phase, so its precision has to be
+    // visible in it. A reason that is mostly assumed is not a finding about an
+    // app; it is a count of things nothing could classify, and reading it as a
+    // verdict on a faculty is how the instrument came to disagree with a
+    // tester who was right.
+    classified_by_reason: classifiedByReason,
+    assumed_by_reason: assumedByReason,
     by_outcome: byOutcome,
+    // Only where the reason was actually read. A faculty named against a pile
+    // of assumptions is advice with nothing behind it.
     faculty: Object.fromEntries(
-      REASONS.filter((r) => byReason[r]).map((r) => [r, `${FACULTY[r]}${BUILT_FACULTIES.has(FACULTY[r]) ? ' [built]' : ''}`]),
+      REASONS.filter((r) => classifiedByReason[r]).map((r) => [r, `${FACULTY[r]}${BUILT_FACULTIES.has(FACULTY[r]) ? ' [built]' : ''}`]),
     ),
     avoidable,
     avoidable_escalation_rate: total ? Number((avoidable / total).toFixed(3)) : null,

package/src/navigate.js

@@ -96,14 +96,40 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
 
   const result = await runScript(udid, { steps, stopOnUnexpected: true, ...runOptions });
   const arrived = await api.screenIdentity(udid, {});
-  return {
-    ok: arrived.hash === found.node.hash,
+  const walk = {
     screen: found.name,
     steps,
     ranSteps: result.ranSteps,
     results: result.results,
     arrived: arrived.hash ? arrived.hash.slice(0, 8) : null,
   };
+  if (arrived.hash === found.node.hash) return { ok: true, ...walk };
+
+  // A walk that ran and did not land had no name, and it was the only outcome
+  // here that did not.
+  //
+  // Every refusal above is named, logged and groupable; this one returned
+  // `{ok: false}` with no `reason` at all, so `simframe goto <known hash>` on
+  // CI failed the check that says *"it either walks there or names why it
+  // cannot"* with an empty detail — which is exactly what the check is for, and
+  // it had been sitting under an outcome nobody had named rather than under a
+  // crash.
+  //
+  // Two names, because they are two different faults and only one of them is
+  // about the graph. `route-halted` means a step on the route failed, which is
+  // an ordinary failure of the app or the moment. `arrived-elsewhere` means
+  // every step ran and we are *not where the graph promised* — an edge it
+  // remembers is wrong, and that is worth reading as a claim about memory
+  // rather than about this attempt.
+  const reason = !arrived.hash
+    ? 'no-identity'
+    : (result.ranSteps < steps.length ? 'route-halted' : 'arrived-elsewhere');
+  return refuse(udid, { ok: false, reason, to: found.name, ...walk }, {
+    detail: reason === 'arrived-elsewhere'
+      ? `route to "${found.name}" ran to the end and landed on ${walk.arrived}`
+      : `route to "${found.name}" stopped after ${result.ranSteps} of ${steps.length} step(s)`,
+    flowName: `goto:${target}`,
+  });
 }
 
 export function knownScreens(udid) {