simframe 0.16.0 → 0.18.0

package/src/device-state.js

@@ -0,0 +1,64 @@
+// Is a failure the device's fault or the code's?
+//
+// Moved out of `scripts/` on 2026-09-17 so `src/metrics.js` can use it. The
+// escalation log needed it: 78 of the `verification_failed` records on the
+// bench device are `xcrun simctl openurl` failing, an app that would not
+// launch, or capture stopping — the device, filed under a code faculty and
+// reported as evidence for "sense of time (Phase 11)". A steering wheel that
+// counts item 173's own occurrences as a perception problem points somewhere
+// nobody chose.
+//
+// Deliberately dependency-free. `wedge.js` imports `index.js`, and `metrics.js`
+// is imported *by* `index.js`, so a shared table living in either would close a
+// cycle. This module imports nothing and is imported by both.
+
+/** Conditions that are the simulator, not the code. Each seen in a real run. */
+export const DEVICE_STATE = [
+  [/NSPOSIXErrorDomain.*code=?\s*60|Operation timed out/i, 'simctl stopped answering (NSPOSIXErrorDomain 60)'],
+  [/did not produce a frame|produced no frame in \d+s/i, 'the daemon is up and the display renders nothing'],
+  [/Timeout waiting for screen surfaces|display surface is not answering|display surface could not be read/i, 'the display surface is wedged'],
+  [/no frames buffered|capture is wedged/i, 'capture stopped'],
+  [/the second app never launched|could not be dispatched/i, 'an app would not launch'],
+  // A launched app that never comes to the front, seen as the tour waiting for
+  // one of its landmarks on a screen that is showing a clock and nothing else.
+  //
+  // Measured on a runner: `ok launch — launched com.apple.Preferences
+  // (relaunched)` followed by `waited 8000ms for General: "General" is not on
+  // this screen. Visible: 10:50, .?o (the screen has not moved for 6181ms)`.
+  // Two labels, one of them a clock, on a still screen — the device is not
+  // presenting the app, and the guard called that a check failing on its
+  // merits and declined to revive.
+  //
+  // Deliberately narrow. It requires the wait to have failed AND the screen to
+  // have been still AND almost nothing readable: a tour that genuinely asks for
+  // the wrong label has a screen full of other labels, and must keep failing
+  // rather than being retried into a pass.
+  [
+    /never arrived[\s\S]*?Visible:[^\n]{0,24}\(the screen has not moved for \d+ms/i,
+    'a launched app never came to the front (the screen shows a clock and nothing else)',
+  ],
+  // The same condition, now said outright by the step that suffered it instead
+  // of inferred from the shape of the screen afterwards. Item 169 gave `launch`
+  // a pid to compare, so a launch that starts a process and never fronts it
+  // reports itself; this signature fires on the cause rather than on a
+  // consequence that had to be recognised by "two labels, one a clock".
+  //
+  // It cannot be triggered by a tour asking for the wrong label — only a failed
+  // launch emits this sentence — so it needs none of the narrowing above.
+  [
+    /never came to the front within \d+ms/i,
+    'a launched app never came to the front (the launch said so itself, by pid)',
+  ],
+  // Seen on the v0.14.3 bench run: `could not launch com.apple.Preferences:
+  // The system shell (SpringBoard:36454) probably crashed.` The guest's window
+  // server going down is the device, not the check, and nothing here matched it.
+  [
+    /system shell \(SpringBoard[^)]*\) probably crashed/i,
+    "the guest's SpringBoard crashed, so nothing can be fronted",
+  ],
+];
+
+/** The condition this output shows, or null when the check failed on its merits. */
+export function deviceCause(text) {
+  return DEVICE_STATE.find(([re]) => re.test(String(text ?? '')))?.[1] ?? null;
+}

package/src/graph.js

@@ -869,7 +869,7 @@ export const VERDICTS = ['ok', 'no-visible-change', 'unexpected-screen', 'unveri
  * that already exists do its job. A string still works and still means "exact
  * match only", which is right for a stored prediction that has no tokens.
  */
-function sameScreen(udid, a, b) {
+export function sameScreen(udid, a, b) {
   const hashOf = (v) => (typeof v === 'string' ? v : v?.hash);
   const ha = hashOf(a);
   const hb = hashOf(b);

package/src/matching.js

@@ -224,8 +224,9 @@ export function rank(targets, intent, { screen } = {}) {
 
   // **A distinctive fragment of one long name, when nothing else came close.**
   //
-  // Reported from the field: `waitFor "6322594"` gave up after 20 s on a screen
-  // whose own "Visible:" list printed `Work Order #6322594`. The reporter's
+  // Reported from the field: a `waitFor` on a seven-digit record number gave up
+  // after 20 s on a screen whose own "Visible:" list printed that number inside
+  // a heading — `Record #<digits>`, seventeen characters. The reporter's
   // guess was that `#` was being treated as significant, or that the matcher
   // was anchored. It is neither — the number scores **0.287** against the 0.45
   // floor, because the substring branch in `nameScore` scales by how much of

package/src/mcp.js

@@ -134,7 +134,7 @@ const TOOLS = [
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
+            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and "optional":true to any step that may legitimately have nothing to act on, which is how you cross a first-launch nag, a permission sheet or a "What\'s New" in one batch — {"tap":"Not Now","optional":true} is skipped when nothing matches and runs normally when it does, so the rest of the plan survives an interstitial that did not appear — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
           items: { type: 'object' },
         },
         autoSettle: {
@@ -1077,11 +1077,25 @@ async function doScript(target, args, options) {
         + ' seen before to compare against. Replay it once with sim_flow_run and it'
         + ' is confirmed. A replay costs no model calls.'
       : ' — confirmed; replay with sim_flow_run for zero model calls';
+    // One sentence per reason, because "incomplete-run" and "failed-steps" ask
+    // for opposite things from the caller and the bare reason names neither.
+    const why = {
+      'contradicted-steps': 'a step landed somewhere memory says it should not have,'
+        + ' so this route is not safe to replay. Check the flagged step before re-running it.',
+      'failed-steps': 'a step ran and failed, so replaying this would fail the same way'
+        + ' every time. Fix the step and re-run the batch, then save.',
+      'incomplete-run': 'the run stopped before its last step, so the rest of the route'
+        + ' was never observed. Re-run it to the end, then save.',
+    }[saved.reason];
+    // `verdicts` has a hole wherever a step never produced one — a failed step
+    // has no verification — and joining those printed `(unverified, unverified, )`.
+    const seen = (saved.verdicts ?? []).filter(Boolean);
     lines.push(
       saved.ok
         ? `saved as flow "${saved.name}" (${saved.steps} steps)${how}`
         : `NOT saved as "${args.saveAs}": ${saved.reason}`
-          + `${saved.verdicts ? ` (${saved.verdicts.join(', ')})` : ''}`,
+          + `${why ? ` — ${why}` : ''}`
+          + `${seen.length ? ` (verdicts: ${seen.join(', ')})` : ''}`,
     );
   }
   const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));
@@ -1167,6 +1181,14 @@ async function flowRun(target, args, options) {
     };
   }
   const lines = [`flow "${args.name}"`, ...stepLines(res)];
+  // Said out loud or not said at all. A flow now records the screen it was
+  // recorded on, and a mismatch that only exists in the return value is a fact
+  // nobody reads — which is the same shape as the check that could not fail.
+  if (res.startedElsewhere) {
+    lines.push(`NOTE: this flow was recorded starting on screen ${res.startedElsewhere.recorded},`
+      + ` and this replay started on ${res.startedElsewhere.here}. Not refused — content-driven`
+      + ' screens legitimately change identity — but if the steps below fail to resolve, this is why.');
+  }
   lines.push('', await mapFrom(target, options, res.endScreen, { verdictLine: verdictLineFor(res.results) }));
   return { content: [text(lines.join('\n'))], isError: !res.ok };
 }

package/src/metrics.js

@@ -12,6 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import * as store from './store.js';
+import { deviceCause } from './device-state.js';
 
 /** The five reasons, from docs/research/03-human-parity.md §8. Nothing else is a reason. */
 export const REASONS = [
@@ -66,6 +67,52 @@ export const FACULTY = {
  */
 export const BUILT_FACULTIES = new Set(['sense of time (Phase 11)']);
 
+/**
+ * The faculty a `verification_failed` record points at, by **verdict**.
+ *
+ * `FACULTY` is keyed on the reason, and for this class the reason is too coarse
+ * to steer by. Measured on the bench device's 1022 records: of the
+ * `verification_failed` ones, 162 are `no-visible-change`, 26 are
+ * `unexpected-screen`, and about 172 are a wait that timed out — three
+ * different faculties, all of which the report named as "sense of time
+ * (Phase 11)" because that is what the reason maps to.
+ *
+ * `unexpected-screen` is the clearest case: it is item 174, screen identity
+ * fragmenting on content-driven screens, and reporting it as a timing problem
+ * is how a tester was once told their unlabeled-control problem was a timing
+ * problem.
+ */
+/**
+ * The verdict a legacy record carries in the first token of its `detail`.
+ *
+ * Written as `${verdict}: ${detail}` since the field existed, so the prefix is
+ * reliable — but only for records whose detail came from a verdict at all,
+ * which is why this returns null rather than guessing on anything else.
+ */
+export function verdictFromDetail(detail) {
+  const m = /^([a-z][a-z-]{3,30}):\s/.exec(String(detail ?? ''));
+  // Only a verdict that exists. The first draft returned any lowercase prefix
+  // and duly reported a verdict called **"capture"** with a count of 8, from
+  // details reading `capture: ...`. A parser that invents a category gets it
+  // counted, named in a report, and eventually used to choose a phase — which
+  // is the whole failure this grouping was added to fix, reproduced inside the
+  // fix.
+  return m && KNOWN_VERDICTS.has(m[1]) ? m[1] : null;
+}
+
+export const VERDICT_FACULTY = {
+  'unexpected-screen': 'screen identity (item 174)',
+  'still-filling-in': 'sense of time (Phase 11)',
+  // **`no-visible-change` is deliberately absent, and it is the largest verdict
+  // in the log (162 of 1022).** The escalation site has a measured argument for
+  // leaving it unclassified and it is right: in the field it came
+  // overwhelmingly from tapping an inert text label whose real hit target was
+  // an invisible chevron — icon semantics, Phase 15 — but it also covers a
+  // switch moving 0.1% of the screen, which is neither faculty. Two causes, one
+  // verdict, and no way to tell them apart from here. Putting it in this map
+  // would name a faculty for 162 records on a coin flip.
+};
+
 function metricPaths(udid) {
   const dir = store.deviceDir(udid);
   return {
@@ -323,6 +370,17 @@ export function reasonForStepError(step, err) {
   // 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.
+  // The device, not a faculty.
+  //
+  // 78 of this class on the bench device are `xcrun simctl openurl` failing, an
+  // app that would not launch, or capture stopping. Those are item 173, and
+  // filing them under a code faculty is how the log came to offer "sense of
+  // time (Phase 11)" as the remedy for a simulator that had stopped answering.
+  // `classified` stays false because no *faculty* was read; `device` says what
+  // was, so the report can take these out of the faculty count instead of
+  // counting them towards a phase.
+  const device = deviceCause(err?.message);
+  if (device) return { reason: 'verification_failed', candidates: [], tried: [], classified: false, device };
   return { reason: 'verification_failed', candidates: [], tried: [], classified: false };
 }
 
@@ -336,6 +394,17 @@ export function reasonForStepError(step, err) {
  */
 export const ESCALATING_VERDICTS = new Set(['unexpected-screen', 'no-visible-change']);
 
+/**
+ * Every verdict the engine can report, for reading legacy details back.
+ *
+ * Wider than `ESCALATING_VERDICTS` — which is the two that hand back to a model
+ * — because a record's detail may carry any of them, and narrower than "any
+ * lowercase word", which is what a prefix parser accepts if nobody bounds it.
+ */
+export const KNOWN_VERDICTS = new Set([
+  'unexpected-screen', 'no-visible-change', 'still-filling-in', 'unverified', 'ok',
+]);
+
 /** How `goto`/`flow run` refusals map. They refuse rather than guess, and the refusal is the hand-back. */
 export const PLAN_REASONS = {
   'unknown-screen': 'unknown_screen',
@@ -463,6 +532,14 @@ export function recordEscalation(udid, {
   // Default `false`, so a caller that does not think about it cannot
   // accidentally claim precision it does not have.
   classified = false,
+  // Which device-state condition this failure shows, when it shows one. Kept
+  // separate from `reason` because the five-reason vocabulary is fixed and a
+  // sixth reason collects a pile of "other" — see REASONS.
+  device = null,
+  // Which local verdict fired, for the records that have one. Derivable from
+  // `detail` today by parsing a prefix, which is exactly the fragility the log
+  // should not depend on.
+  verdict = null,
 } = {}) {
   if (!REASONS.includes(reason)) throw new Error(`not an escalation reason: ${reason}`);
   if (!OUTCOMES.includes(outcome)) throw new Error(`not an escalation outcome: ${outcome}`);
@@ -479,6 +556,10 @@ export function recordEscalation(udid, {
     // 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),
+    // Null unless read. Both of these separate "we know" from "we assumed" for
+    // a class that is otherwise one coarse bucket.
+    device_cause: device ? String(device).slice(0, 120) : null,
+    verdict: verdict ? String(verdict).slice(0, 60) : null,
     step_index: stepIndex,
     screen_fingerprint: fingerprint,
     reason,
@@ -538,7 +619,9 @@ export function flowRecordFrom({
     images_sent: imagesSent,
     input_tokens: null,
     output_tokens: null,
-    escalations: escalations.map((e) => ({ reason: e.reason, step_index: e.step_index, outcome: e.outcome })),
+    escalations: escalations.map((e) => ({
+      reason: e.reason, step_index: e.step_index, outcome: e.outcome, device_cause: e.device_cause ?? null,
+    })),
     escalation_count: escalations.length,
     mis_taps: misTaps,
     verdict_histogram: histogram,
@@ -546,6 +629,22 @@ export function flowRecordFrom({
     exploration_events: [],
     completed: Boolean(completed),
     wrong_action_taken: verdicts.includes('unexpected-screen'),
+    // Did this run fail because the *simulator* failed?
+    //
+    // Measured, on a full local suite: of 17 runs, 5 failed because the guest's
+    // SpringBoard crashed or `simctl` stopped answering for 90 s. `hpi`
+    // counted every one against `HPI_accuracy`, so the gate CI reads was partly
+    // measuring SpringBoard's stability.
+    //
+    // This is item 172 in the other column. There, `HPI_time` took every run's
+    // wall clock regardless of completion, so breaking a flow registered as the
+    // agent getting quicker; the fix was to time only completed runs. Accuracy
+    // had the mirror-image fault and kept it.
+    //
+    // Derived from the escalations this run already wrote — `device_cause` is
+    // set at the step that suffered it — so nothing new has to be plumbed and a
+    // run cannot claim a device fault that its own log does not show.
+    device_cause: escalations.map((e) => e.device_cause).find(Boolean) ?? null,
   };
 }
 
@@ -691,8 +790,14 @@ export function hpi({ flows, baselines = {} }) {
     };
   }).sort((a, b) => a.flow.localeCompare(b.flow));
 
-  const total = flows.length;
-  const clean = flows.filter((f) => f.completed && !f.wrong_action_taken).length;
+  // A run the simulator broke is not a run the code got wrong. It is an
+  // **unmeasured** run, and it leaves the denominator rather than lowering the
+  // score — the same discipline as timing only completed runs (172), and the
+  // same discipline as the suite refusing to publish a partial HPI at all.
+  const lostToDevice = flows.filter((f) => f.device_cause && !f.completed);
+  const measurable = flows.filter((f) => !(f.device_cause && !f.completed));
+  const total = measurable.length;
+  const clean = measurable.filter((f) => f.completed && !f.wrong_action_taken).length;
   const accuracy = total ? Number((clean / total).toFixed(3)) : null;
   const times = perFlow.map((f) => f.hpi_time).filter((x) => Number.isFinite(x));
   const hpiTime = harmonicMean(times);
@@ -700,6 +805,11 @@ export function hpi({ flows, baselines = {} }) {
     flows: perFlow,
     overall: {
       runs: total,
+      // Said out loud, because a denominator that quietly shrinks is worse than
+      // one that is wrong: an accuracy of 1.0 over two measurable runs is not
+      // the same claim as 1.0 over eighteen.
+      runs_lost_to_device: lostToDevice.length,
+      device_causes: [...new Set(lostToDevice.map((f) => f.device_cause))],
       flows_measured: perFlow.length,
       flows_with_human_baseline: times.length,
       hpi_accuracy: accuracy,
@@ -728,12 +838,20 @@ export function breakdown(records, { session = null, flow = null } = {}) {
   const classifiedByReason = {};
   const assumedByReason = {};
   for (const r of REASONS) { byReason[r] = 0; classifiedByReason[r] = 0; assumedByReason[r] = 0; }
+  // Two more groupings, because the reason alone could not steer. `byVerdict`
+  // splits the largest class into the three different things it holds, and
+  // `byDevice` takes out the records that are the simulator rather than the
+  // code — those were being counted towards a perception phase.
+  const byVerdict = new Map();
+  const byDevice = new Map();
   const byScreen = new Map();
   const byOutcome = {};
   const bySession = new Map();
   const byFlow = new Map();
   let avoidable = 0;
   let unattributed = 0;
+  let derivedVerdicts = 0;
+  let derivedDevice = 0;
   // Filtering happens here rather than at the call site so `total` and every
   // rate below it describe the same set of records.
   const kept = records.filter((r) => (session ? r?.session_id === session : true))
@@ -757,6 +875,18 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     // 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;
+    // Derived for the records that predate the fields, rather than waiting for
+    // a fresh corpus. `detail` already carries both facts — the verdict as its
+    // prefix, the device signature inside the message — so a read-time
+    // derivation turns 1022 existing records into signal without rewriting a
+    // single line of the log. Marked in the output as derived, because a
+    // recorded fact and a parsed one are not the same evidence.
+    const verdict = r.verdict ?? verdictFromDetail(r.detail);
+    const device = r.device_cause ?? deviceCause(r.detail);
+    if (verdict) byVerdict.set(verdict, (byVerdict.get(verdict) ?? 0) + 1);
+    if (device) byDevice.set(device, (byDevice.get(device) ?? 0) + 1);
+    if (!r.verdict && verdict) derivedVerdicts += 1;
+    if (!r.device_cause && device) derivedDevice += 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;
@@ -770,8 +900,19 @@ export function breakdown(records, { session = null, flow = null } = {}) {
       return { session_id: id, client, count };
     })
     .sort((a, b) => b.count - a.count);
+  const sorted = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]).map(([name, count]) => ({ name, count }));
   return {
     total,
+    // What the reason could not say. `verdicts` is the largest class split into
+    // the faculties it actually implies; `device` is the part that is item 173
+    // wearing a code reason.
+    verdicts: sorted(byVerdict),
+    device: sorted(byDevice),
+    device_total: [...byDevice.values()].reduce((a, b) => a + b, 0),
+    // How much of the two groupings above was parsed out of `detail` rather
+    // than recorded at the time. A reader deciding a phase order should know
+    // which half they are looking at.
+    derived: { verdicts: derivedVerdicts, device: derivedDevice },
     // The log is per-device and shared: two agents on one booted simulator
     // write one interleaved file. More than one session here means the counts
     // below are a pool, and CLAUDE.md uses those counts to choose a phase.

package/src/navigate.js

@@ -47,6 +47,16 @@ function refuse(udid, result, { detail = null, flowName = null } = {}) {
     if (reason) {
       metrics.recordEscalation(udid, {
         reason,
+        // Read, not assumed. `recordEscalation` defaults `classified` to false
+        // so a careless caller cannot claim precision it does not have, which
+        // is right — and this caller is not careless: `result.reason` is a
+        // named refusal (`no-route`, `unreplayable-edge`, `unknown-flow`,
+        // `arrived-elsewhere`…) and PLAN_REASONS maps it deterministically.
+        // Saying nothing filed 82 records on the bench device as "reason
+        // assumed" when the reason was known exactly, which makes the log
+        // understate its own knowledge and the report decline to name a
+        // faculty it was entitled to name.
+        classified: true,
         // A refusal by `goto` is about a destination and one by `flow run` is
         // about a named flow. Either is what a breakdown wants to group by.
         flowName,
@@ -170,14 +180,31 @@ const CONTRADICTED = /^unexpected/;
  * and a flow that did not reach its own last step.
  */
 export function saveFlow(udid, name, script, { force = false } = {}) {
-  const verdicts = (script.results ?? []).map((r) => r.verification?.verdict);
+  const results = script.results ?? [];
+  const verdicts = results.map((r) => r.verification?.verdict);
   const contradicted = verdicts.filter((v) => v && CONTRADICTED.test(v));
   const ranAll = script.ranSteps == null
     || script.steps == null
     || script.ranSteps >= (script.steps?.length ?? 0);
+  // A step that ran and failed is not a step that ran.
+  //
+  // `ranSteps` counts steps *attempted*, and a failing step stops the batch —
+  // so a run whose failure is on the **last** step has `ranSteps === steps.length`
+  // and passed the gate above. A peer watched `FLOW FAILED — 4 ok, 1 failed (of
+  // 5)` save itself as a flow, which is a flow guaranteed to fail forever. The
+  // predicate wanted "every step succeeded" and was written as "every step was
+  // reached"; on every run except one they are the same sentence.
+  //
+  // `!r.ok` rather than `r.ok === false` on purpose: a result that does not say
+  // it succeeded has not said it succeeded, and a gate that only catches an
+  // explicit `false` is one absent field away from being unable to fail.
+  const failedSteps = results.filter((r) => !r.ok);
   if (!force && contradicted.length) {
     return { ok: false, reason: 'contradicted-steps', verdicts };
   }
+  if (!force && failedSteps.length) {
+    return { ok: false, reason: 'failed-steps', verdicts, failed: failedSteps.map((r) => r.index ?? null) };
+  }
   if (!force && !ranAll) {
     return { ok: false, reason: 'incomplete-run', verdicts };
   }
@@ -249,6 +276,28 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
   // a human doing the same thing. `minSteps` comes from the flow definition or
   // stays null — the step count of a recorded route is not a claim about the
   // shortest one.
+  // Is this the screen the flow was recorded on?
+  //
+  // Reported, not refused, and the distinction is deliberate. A replay from the
+  // wrong screen is mostly self-limiting — the first selector does not resolve
+  // and the run stops one step in, and the destructive vocabulary is barred by
+  // the verify barrier either way. Refusing on a mismatch would put the exact
+  // failure mode of item 174 — content-driven screens fragmenting into several
+  // identities — in front of the one path that costs zero model calls. So this
+  // says what it saw and lets the run proceed, which also measures how often
+  // the mismatch is spurious. If it turns out to be rare, it can become a gate;
+  // deciding that by reasoning is how 174 got built in the first place.
+  let startedElsewhere = null;
+  if (flow.startScreen?.hash) {
+    try {
+      const here = await api.screenIdentity(device.udid, {});
+      if (here.hash && !graph.sameScreen(device.udid, here, flow.startScreen)) {
+        startedElsewhere = { recorded: flow.startScreen.hash.slice(0, 8), here: here.hash.slice(0, 8) };
+      }
+    } catch {
+      /* not knowing where we are is not a reason to refuse to try */
+    }
+  }
   const result = await runScript(device.udid, {
     steps: flow.steps,
     stopOnUnexpected: true,
@@ -256,11 +305,18 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
     minSteps: flow.minSteps ?? null,
     ...runOptions,
   });
-  const ok = result.ranSteps === flow.steps.length;
+  // Same arithmetic as `saveFlow`, and the same defect: reaching the last step
+  // is not passing it. `result.ok` is the run's own verdict and was ignored
+  // here, so a replay that failed on its final assert promoted the flow it had
+  // just disproved. Both of a peer's saved flows were marked confirmed by
+  // replays that failed; the word "clean" in "confirmed by one clean replay"
+  // did not exist in the code path.
+  const everyStepPassed = (result.results ?? []).every((r) => r.ok);
+  const ok = result.ok !== false && everyStepPassed && result.ranSteps === flow.steps.length;
   // A clean replay is the confirmation a first traversal could not give.
   // Only when nothing was contradicted — a replay that ran to the end while
   // objecting to a step is not a promotion.
   const objected = (result.results ?? []).some((r) => CONTRADICTED.test(r.verification?.verdict ?? ''));
   const promoted = ok && !objected ? confirmFlow(device.udid, name) : false;
-  return { ok, name, ...result, ...(promoted ? { promoted: true } : {}) };
+  return { ok, name, ...result, ...(promoted ? { promoted: true } : {}), ...(startedElsewhere ? { startedElsewhere } : {}) };
 }