simframe 0.17.0 → 0.18.0

package/README.md

@@ -751,6 +751,30 @@ project: **there is nothing left to win inside the engine.** 1.7 s is small
 beside a 20 s round trip, so making perception or input faster buys single-digit
 percentages. The only variable that matters is `n` — how many steps one decision
 covers. Every improvement here has come from raising it, not from faster code.
+
+### One more term: the launch is a fixed cost
+
+Measured on the benchmark suite with **no model in the loop at all**:
+
+| route | steps | agent | per step | human | per step |
+| --- | --- | --- | --- | --- | --- |
+| contacts-kate-bell | 2 | 12419 ms | **6.2 s** | 4300 ms | 2.15 s |
+| settings-larger-text | 4 | 15281 ms | 3.8 s | 7799 ms | 1.95 s |
+
+2.9× a human on the short route with nothing thinking, which does not fit
+`1.7s × n`. A cold app launch is a **one-off cost amortised over the route**:
+
+```
+per step = (model round trip + launch cost + ~1.7s × n) / n
+```
+
+That reconciles a 7-step replay at 1.82 s/step with a 2-step route at 6.2 s/step
+— one launch spread over 7 steps or over 2. **The `~1.7 s` figure is warm taps
+inside a batch**, and short routes are materially worse than the table above
+implies on its own.
+
+`step_ratio` was **1** throughout: when a run completed it took exactly the
+minimum number of steps.
 A field report put the split at **34% simframe, 60% agent round trips** over
 462 s of wall clock — the tester's *"30+ seconds between each step"* was
 accurate and was not simframe. So there is nothing left to win inside the
@@ -871,6 +895,7 @@ simframe supervisions          # local supervisor rulings, and what came of each
 simframe hpi                   # speed and accuracy against a human baseline
 simframe baseline record settings-larger-text --runs=5   # record the human
 simframe input reset           # rebuild the HID session, without restarting anything
+simframe diagnose              # what this device is doing right now, and which failure it is
 simframe revive                # power-cycle a wedged device: stop, shutdown, boot, start, reset input
 simframe start / status / stop [--force] / devices
 simframe ui --device=emulator-5554      # or export SIMFRAME_DEVICE once
@@ -895,6 +920,29 @@ rebinds, no frame since). This needs the device restarted —
 `simframe revive --device=<udid>`. Backing off until a frame arrives.
 ```
 
+**`simframe diagnose` says which failure it is**, which `doctor` cannot: `doctor`
+answers "can this machine capture", and this answers "what is this device doing
+right now". It reads only what discriminates — frame sequence, age and
+stillness, element counts split by sensor, how many of them fuse, and who holds
+the front by pid — and returns one of:
+
+| verdict | what it means |
+| --- | --- |
+| `capture-down` | no frames at all, carrying the daemon's own sentence |
+| `nothing-readable` | frames arriving, neither sensor finds a single element |
+| `stale-frame` | both sensors full, almost nothing fuses — the framebuffer is behind the tree, so **an image from this device is not safe to trust** |
+| `not-presenting` | an app holds the front by pid and the display shows almost nothing |
+| `healthy` | — |
+
+`not-presenting` deliberately does **not** say whether that is a lock screen, a
+dead surface or a crashed system shell. It is not knowable from here, and
+guessing is how a regex ended up standing where a measurement belongs.
+
+The `stale-frame` threshold is measured rather than chosen: element fusion on
+five healthy screens ran 0.667–0.929, so the threshold sits at 0.1 — 6.7× below
+the observed floor rather than inside the metric's own noise. Numbers in
+[`docs/BENCHMARKS.md`](docs/BENCHMARKS.md).
+
 `simframe revive` is that restart, in the order that matters — stop the daemon,
 shut the device down, boot it and *wait for the boot to finish*, start capture,
 rebuild the HID session — and it ends by checking frames are flowing again

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/bench-hpi.mjs

@@ -191,6 +191,14 @@ for (const f of report.flows) {
 report.overall.hpi_time_median_of_passes = passTimes.length ? Number(metrics.median(passTimes).toFixed(3)) : null;
 const o = report.overall;
 console.log(`\nHPI_accuracy ${o.hpi_accuracy}   HPI_time ${o.hpi_time ?? '—'}   HPI ${o.hpi ?? '—'}   step_ratio ${o.step_ratio ?? '—'}`);
+if (o.runs_lost_to_device) {
+  // Measured on a full local suite: 5 of 17 runs failed because the guest's
+  // SpringBoard crashed or simctl stopped answering. They used to lower
+  // HPI_accuracy, which is the number this job gates on.
+  console.log(`  over ${o.runs} measurable run(s); ${o.runs_lost_to_device} left the denominator`
+    + ' because the DEVICE failed, not the code (item 173):');
+  for (const c of o.device_causes ?? []) console.log(`    ${c}`);
+}
 if (passTimes.length > 1) {
   console.log(`HPI_time per pass: ${passTimes.join(', ')} — median ${o.hpi_time_median_of_passes} (what the gate reads)`);
 }

package/scripts/ci-device-guard.mjs

@@ -59,6 +59,25 @@ if (!cause) {
   process.exit(first.code ?? 1);
 }
 
+// Diagnose BEFORE reviving, because reviving is what destroys the evidence.
+//
+// This guard has been recognising wedges from the shape of the failure text
+// since 126, and then immediately power-cycling the device — so item 173 has
+// accumulated a dozen occurrences and not one observation of what the device
+// was doing at the time. `cause` above names a *consequence* ("a launched app
+// never came to the front"); this names what the two sensors actually saw, and
+// the difference decides between a stale framebuffer, a screen that is not the
+// app, and capture being down. Its cost is one read on a path that is already
+// failing.
+const diagnose = async (when) => {
+  const d = await run(['node', 'src/cli.js', 'diagnose', `--device=${udid}`]);
+  console.error(`\n     (diagnosis ${when} — for DEFERRED 173)`);
+  const verdict = /— (\S+)\n/.exec(d.out)?.[1] ?? 'unreadable';
+  summary(`  - diagnosis ${when}: \`${verdict}\``);
+  return verdict;
+};
+const before = await diagnose('before the revive');
+
 console.error(`\n     (${cause} — DEFERRED 126. Reviving once and running again.)`);
 await run(['node', 'src/cli.js', 'revive', `--device=${udid}`], { capture: false });
 const second = await run(cmd);
@@ -70,4 +89,12 @@ if (second.code === 0) {
 const again = deviceCause(second.out);
 summary(`- \`${cmd.join(' ')}\` — **${again ? 'device unavailable' : 'check failed'}** after a revive${again ? ` (${again})` : ''}`);
 if (again) console.error(`\nFAIL the simulator is still in a bad state after a revive: ${again}`);
+// Twice is the interesting case: a revive cured it and it came back, or the
+// revive did not cure it at all. Those are different faults and the pair of
+// diagnoses says which.
+const after = await diagnose('after the revive');
+if (before !== after) {
+  console.error(`\n     (the device changed state across the revive: ${before} -> ${after})`);
+  summary(`  - state changed across the revive: \`${before}\` -> \`${after}\``);
+}
 process.exit(second.code ?? 1);

package/scripts/device-state.mjs

@@ -1,62 +1,5 @@
-// Is a failed CI step the device's fault or the check's?
-//
-// Its own module, and the reason is the same one that moved `classifyStray` out
-// of `eval-fingerprint.mjs`: `ci-device-guard.mjs` reads `process.argv` and
-// `process.exit(2)`s at import, so nothing could ever test this table there —
-// and the only thing that exercised it was a hosted runner, at the end of a
-// fifteen-minute job, in the middle of a report. Two runtime bugs in this
-// project came from logic that was correct and had never executed.
-//
-// Every entry here has been seen in a real run. Adding one from imagination is
-// how a guard starts reviving genuine failures into passes.
-
-/** 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;
-}
+// Kept as a re-export: the table moved to `src/device-state.js` so `src/` can
+// use it without importing out of `scripts/`. `ci-device-guard.mjs` and the
+// unit test both reach it through this path, and a redirect is cheaper than
+// updating every caller for a move that changes nothing about the table.
+export { DEVICE_STATE, deviceCause } from '../src/device-state.js';

package/src/actions.js

@@ -933,7 +933,19 @@ export async function runScript(
           // switch moving 0.1% of the screen, which is neither faculty. Saying
           // "assumed" is the honest answer; guessing a better-sounding reason
           // would be the same mistake in the other direction.
-          classified: false,
+          //
+          // **Per verdict, though, not per site.** That argument is about
+          // `no-visible-change` and does not extend to every verdict: an
+          // `unexpected-screen` means the screen after the action was not the
+          // one memory predicted, which is item 174 and nothing else.
+          // `metrics.VERDICT_FACULTY` holds the verdicts whose faculty is read,
+          // and `no-visible-change` is deliberately not one of them — so this
+          // still says "assumed" for the 162 records the reasoning above is
+          // actually about, and stops saying it for the 26 it never covered.
+          classified: Boolean(metrics.VERDICT_FACULTY[verification?.verdict]),
+          // Recorded as a field rather than left as a prefix of `detail`, which
+          // is how the breakdown had to recover it: by parsing a string.
+          verdict: verification?.verdict ?? null,
           // `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
@@ -989,6 +1001,11 @@ export async function runScript(
       const why = metrics.reasonForStepError(step, err);
       noteEscalation({
         stepIndex: i,
+        // When the failure is the simulator rather than the code, say so. 78 of
+        // the bench device's `verification_failed` records are `simctl` failing,
+        // an app that would not launch, or capture stopping — item 173, counted
+        // towards a perception phase.
+        device: why.device ?? null,
         fingerprint: beforeScreen?.hash ?? metrics.fingerprintNow(udid, screenmap),
         reason: why.reason,
         candidates: why.candidates,

package/src/cli.js

@@ -11,6 +11,7 @@ import * as input from './input.js';
 import * as baseline from './baseline.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
+import * as wedge from './wedge.js';
 import { decodePng } from './png.js';
 import * as storage from './storage.js';
 import * as store from './store.js';
@@ -51,6 +52,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe escalations [device]      why simframe handed decisions back, by reason
   simframe supervisions [device]     local supervisor rulings, and what came of each
   simframe revive [device]           power-cycle a wedged device: stop, shutdown, boot, start, reset input
+  simframe diagnose [device]         what this device is doing right now, and which failure it is
                                      (--session=<id> narrows to one agent; the
                                      ids are listed in the output. SIMFRAME_SESSION
                                      names one, but only at process start — an
@@ -447,6 +449,26 @@ async function main() {
       return;
     }
 
+    // Not folded into `doctor`, which answers "can this machine capture". This
+    // answers "what is this device doing right now", which is item 173's
+    // question and has never had an instrument.
+    case 'diagnose': {
+      const dev = await resolveDevice(device);
+      const r = await wedge.diagnose(dev.udid, { options });
+      emit(flags, r, [
+        `${r.device.name} — ${r.verdict.state}`,
+        `  ${r.verdict.detail}`,
+        '',
+        `  frame      seq ${r.frame?.seq ?? '-'}, ${r.frame?.ageMs ?? '-'}ms old, still for ${r.frame?.stableForMs ?? '-'}ms, ${r.frame?.size ?? '-'}`,
+        `  elements   ${r.elements.total} total — ${r.elements.ax} by tree, ${r.elements.ocr} by OCR, ${r.elements.fused} by both`,
+        `  fusion     ${r.agreement ?? 'n/a'} of elements seen by both sensors (measured healthy ${wedge.HEALTHY_FUSION}; at or below ${wedge.DISAGREEMENT} the frame is stale)`,
+        `  frontmost  ${r.frontmost?.pid ?? 'unknown'}${r.frontmost?.title ? ` (${r.frontmost.title})` : ''}`,
+        ...(r.verdict.revive ? ['', '  `simframe revive` is the recovery. Keep this output — item 173 needs it.'] : []),
+      ]);
+      if (r.verdict.revive) process.exitCode = 1;
+      return;
+    }
+
     case 'status': {
       const udids = device
         ? [(await resolveDevice(device)).udid]
@@ -1253,8 +1275,14 @@ async function main() {
         'flow                      runs  agent p50   human p50   HPI_time  step_ratio  turns  esc',
         ...report.flows.map((f) => metrics.flowRow(f, { wide: true })),
         '',
-        `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} runs, ` +
+        `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} measurable run(s), ` +
           `${report.overall.runs - runs.filter((r) => r.completed && !r.wrong_action_taken).length} not clean)`,
+        // A denominator that quietly shrinks is worse than one that is wrong.
+        report.overall.runs_lost_to_device
+          ? `  ${report.overall.runs_lost_to_device} further run(s) left the denominator because the DEVICE failed,`
+            + ' not the code — those are unmeasured, not inaccurate (item 173):'
+            + `\n${(report.overall.device_causes ?? []).map((c) => `    ${c}`).join('\n')}`
+          : null,
         report.overall.hpi_time == null
           ? `HPI_time and HPI need a human baseline — none of ${report.overall.flows_measured} measured flow(s) has one yet.`
           : `HPI_time ${report.overall.hpi_time} (harmonic mean over ${report.overall.flows_with_human_baseline} flow(s)), HPI ${report.overall.hpi}`,
@@ -1265,7 +1293,10 @@ async function main() {
         `steps per model call ${report.overall.steps_per_call ?? '—'}`
           + (report.overall.steps_per_call
             ? ` — about ${(((20000 + 1700 * report.overall.steps_per_call) / report.overall.steps_per_call) / 1000).toFixed(1)}s`
-              + ' per step end to end, of which simframe is ~1.7s. Raise this, not the engine.'
+              + ' per step end to end. Raise this, not the engine — but note the ~1.7s'
+              + ' figure for simframe\'s own work is WARM taps inside a batch: a cold app'
+              + ' launch is a large one-off on top, and it dominates short flows'
+              + ' (measured: 6.2s/step over 2 steps with no model at all).'
             : ''),
         flags.out ? `wrote ${flags.out}` : null,
       ]);
@@ -1354,13 +1385,45 @@ async function main() {
             if (read > 0) {
               verdict = named + (read < n ? ` (on the ${read} of ${n} whose reason was read)` : '');
             } else if (assumed > 0) {
-              verdict = 'reason assumed, not read — no faculty can be named from these';
+              // For `verification_failed` this line used to end the story, and
+              // it is no longer the whole truth: the verdict split below names
+              // a faculty for some of them and takes the device's own failures
+              // out altogether.
+              verdict = r === 'verification_failed' && (b.verdicts?.length || b.device_total)
+                ? 'reason too coarse to steer by — see the verdict split below'
+                : 'reason assumed, not read — no faculty can be named from these';
             } else {
               // Neither read nor assumed: the log predates the distinction.
-              verdict = `${named} — but these records predate the check, so treat it as untested`;
+              verdict = `${named} — but these records predate the check, so treat it as untested`
+                + ' (legacy, not assumed)';
             }
             return `  ${r.padEnd(20)} ${String(n).padStart(4)}   ${verdict}`;
           }),
+        // The two things the reason alone could not say.
+        //
+        // Both exist because the per-reason table above was the steering wheel
+        // and it pointed at one faculty for a class holding three, and counted
+        // the simulator's own failures towards a perception phase.
+        b.verdicts?.length ? '' : null,
+        b.verdicts?.length
+          ? 'verification_failed, split by the verdict that fired'
+            + (b.derived?.verdicts
+              ? ` (${b.derived.verdicts} of ${b.verdicts.reduce((a, v) => a + v.count, 0)} derived from the detail text, not recorded at the time):`
+              : ':')
+          : null,
+        ...(b.verdicts ?? []).slice(0, 8).map((v) => {
+          const faculty = metrics.VERDICT_FACULTY[v.name];
+          return `  ${v.name.padEnd(20)} ${String(v.count).padStart(4)}   `
+            + (faculty
+              ? `points at: ${faculty}`
+              : 'no faculty follows from this verdict alone — see metrics.VERDICT_FACULTY');
+        }),
+        b.device_total ? '' : null,
+        b.device_total
+          ? `${b.device_total} escalation(s) were the DEVICE, not the code — item 173, and not evidence for any faculty`
+            + `${b.derived?.device ? ` (${b.derived.device} derived from the detail text)` : ''}:`
+          : null,
+        ...(b.device ?? []).slice(0, 6).map((d) => `  ${String(d.count).padStart(4)}  ${d.name}`),
         b.total ? '' : null,
         b.total ? `avoidable ${b.avoidable}/${b.total} (${b.avoidable_escalation_rate})` : null,
         // Said out loud rather than left for someone to discover: the rate is

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/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,

package/src/wedge.js

@@ -0,0 +1,218 @@
+// What is this device actually doing right now?
+//
+// `doctor` answers "can this machine capture". This answers a different
+// question, and it is the one item 173 has never been able to answer: when a
+// device stops presenting the app, *which* of several failures is it?
+//
+// The reason this exists is that the evidence has been arriving as a
+// consequence rather than an observation. `scripts/device-state.mjs` recognises
+// a wedge from the shape of a tour's failure text — "two labels, one of them a
+// clock, on a still screen" — and names it "a launched app never came to the
+// front". That classification is useful for deciding whether to revive, and it
+// is not a diagnosis: it cannot tell a dead framebuffer from a device that is
+// genuinely showing a lock screen from an app that never fronted. Three
+// hypotheses, one symptom, and a regex standing where a measurement should be.
+//
+// So the facts get gathered at the moment of the wedge instead of inferred
+// afterwards, and the classifier over them is a **pure function** with fixtures.
+// That part is deliberate: `device-state.mjs` records that "two runtime bugs in
+// this project came from logic that was correct and had never executed",
+// because the only thing exercising it was a hosted runner at minute fifteen of
+// a job. Nothing here needs a device to be tested.
+import * as api from './index.js';
+import * as frontmost from './frontmost.js';
+
+/**
+ * How little agreement between the sensors counts as "these are different
+ * screens".
+ *
+ * **Measured, and the first version of this constant was justified with the
+ * wrong number.** It cited CLAUDE.md's "the tree and OCR agree on 0.33–0.47",
+ * which is a figure about *structural tokens* — a different quantity from the
+ * element-level fusion counted here. Printing a healthy band of 0.33–0.47 next
+ * to a live reading of 0.846 is how that got noticed.
+ *
+ * Sampled on `326464A4` (iPhone 17 Pro, iOS 26.5) across five real screens —
+ * Settings root, General, About, springboard, Reminders:
+ *
+ *   0.857  0.833  0.929  0.846  0.667      median 0.846
+ *
+ * So healthy element fusion is **0.67-0.93** (stated as 0.66 so a reading at the floor does not print as below it), and the floor belongs to the
+ * sparsest screen, which is also the case `ENOUGH_TO_COMPARE` withholds
+ * judgement on. A threshold of 0.1 sits 6.7x below the observed floor: this is
+ * not a band inside the metric's own noise, which is the mistake the HPI_time
+ * gate made.
+ *
+ * What the collapse means: the tree is read live and in-process, OCR reads a
+ * framebuffer that can go stale without saying so. If both sensors report
+ * plenty and almost nothing fuses, they are looking at different screens, and
+ * the frame is the one that is behind. A peer hit exactly this — `sim_look`
+ * returned a web form from an earlier session on the device while the element
+ * map, taken at the same moment, correctly described the app in front of them.
+ */
+export const DISAGREEMENT = 0.1;
+
+/** The range observed on healthy screens, for the report to print honestly. */
+export const HEALTHY_FUSION = '0.66-0.93';
+
+/**
+ * Both sensors need at least this many elements before their disagreement means
+ * anything. A screen with one label from each cannot be said to disagree, and a
+ * springboard or a lock screen is legitimately sparse.
+ */
+export const ENOUGH_TO_COMPARE = 3;
+
+/** At or below this from both sensors, there is effectively nothing on screen. */
+export const SPARSE = 2;
+
+const seenBy = (targets, sensor) =>
+  targets.filter((t) => String(t.source ?? '').split('|').includes(sensor)).length;
+
+/**
+ * Read everything that discriminates between the failure modes, in one pass.
+ *
+ * Every field here exists because it separates two hypotheses. Nothing is
+ * collected because it is interesting.
+ */
+export async function snapshot(deviceQuery, { options } = {}) {
+  // **`ensureDaemon` throws on the loudest condition this module exists to
+  // name.** "the daemon is running and the display produced no frame in 60s" is
+  // reported as an exception, so the first version of this function propagated
+  // it and `simframe diagnose` died with a stack trace on a genuinely wedged
+  // device — the one moment it is worth running. Caught within an hour of
+  // shipping, by the device wedging.
+  //
+  // So a snapshot of a dead device is a snapshot, not an error. `classify`
+  // already has a verdict for it.
+  let device;
+  let state = null;
+  let daemonError = null;
+  try {
+    ({ device, state } = await api.ensureDaemon(deviceQuery, options));
+  } catch (err) {
+    daemonError = err.message;
+    device = { udid: String(deviceQuery ?? '?'), name: String(deviceQuery ?? 'unknown device') };
+  }
+  const udid = device.udid;
+  if (daemonError) {
+    return {
+      device: { udid, name: device.name },
+      readError: daemonError,
+      frame: null,
+      elements: { total: 0, ax: 0, ocr: 0, fused: 0 },
+      agreement: null,
+      frontmost: null,
+    };
+  }
+
+  let identity = null;
+  let readError = null;
+  try {
+    identity = await api.screenIdentity(udid, { options, confirmNovel: false });
+  } catch (err) {
+    readError = err.message;
+  }
+  const targets = identity?.entry?.targets ?? [];
+
+  // Who holds the front, by pid, which is item 169's contribution and the only
+  // sensor here that does not go through the display at all.
+  let front = null;
+  try {
+    front = await frontmost.read(udid);
+  } catch (err) {
+    front = { pid: null, title: null, error: err.message };
+  }
+
+  const ax = seenBy(targets, 'ax');
+  const ocr = seenBy(targets, 'ocr');
+  const fused = targets.filter((t) => {
+    const parts = String(t.source ?? '').split('|');
+    return parts.includes('ax') && parts.includes('ocr');
+  }).length;
+
+  return {
+    device: { udid, name: device.name },
+    readError,
+    frame: state
+      ? {
+          seq: state.seq ?? null,
+          ageMs: state.capturedAt ? Date.now() - state.capturedAt : null,
+          stableForMs: state.stableForMs ?? null,
+          size: state.width && state.height ? `${state.width}x${state.height}` : null,
+          hash: state.hash ? String(state.hash).slice(0, 8) : null,
+        }
+      : null,
+    elements: { total: targets.length, ax, ocr, fused },
+    // Null rather than a number when it cannot be computed, so a caller cannot
+    // read "0 agreement" off a screen nobody could compare.
+    agreement: ax > 0 && ocr > 0 ? Number((fused / Math.min(ax, ocr)).toFixed(3)) : null,
+    frontmost: front,
+  };
+}
+
+/**
+ * Name the state, or say it looks fine.
+ *
+ * Ordered most specific first, and each verdict says what it is evidence *of*
+ * rather than what to do about it — the same discipline as the escalation
+ * reasons, where a vocabulary that admits "other" collects a pile of "other".
+ */
+export function classify(snap) {
+  if (!snap?.frame) {
+    return {
+      state: 'capture-down',
+      // The daemon's own words when it has them. They are more specific than
+      // anything derivable here — "produced no frame in 60s" distinguishes a
+      // live daemon over a dead display from a daemon that is not running.
+      detail: snap?.readError
+        ? `capture is not producing frames: ${snap.readError}`
+        : 'no frame state at all — the daemon is not producing frames',
+      revive: true,
+    };
+  }
+  const { total, ax, ocr } = snap.elements ?? { total: 0, ax: 0, ocr: 0 };
+  if (snap.readError) {
+    return { state: 'read-failed', detail: `the screen could not be read: ${snap.readError}`, revive: true };
+  }
+  if (total === 0) {
+    return {
+      state: 'nothing-readable',
+      detail: 'neither the accessibility tree nor OCR found a single element',
+      revive: true,
+    };
+  }
+  // The two sensors are describing different screens. The tree is read live and
+  // in-process; OCR reads the framebuffer. So the frame is the stale one.
+  if (ax >= ENOUGH_TO_COMPARE && ocr >= ENOUGH_TO_COMPARE
+    && snap.agreement != null && snap.agreement <= DISAGREEMENT) {
+    return {
+      state: 'stale-frame',
+      detail: `the tree found ${ax} element(s) and OCR found ${ocr}, and they fuse on `
+        + `${snap.agreement} of them (measured healthy: ${HEALTHY_FUSION}). The tree is read live, `
+        + 'so the framebuffer is the one that is behind — an image from this device is not safe to trust',
+      revive: true,
+    };
+  }
+  // An app holds the front, and the display is showing almost nothing. This is
+  // the CI signature that `device-state.mjs` recognises as "a clock and nothing
+  // else", now stated as an observation. It deliberately does NOT claim to know
+  // whether this is a lock screen, a dead surface or a crashed SpringBoard —
+  // that is the next question, and pretending to answer it is what put a regex
+  // where a measurement belongs.
+  if (snap.frontmost?.pid && ax <= SPARSE && ocr <= SPARSE) {
+    return {
+      state: 'not-presenting',
+      detail: `pid ${snap.frontmost.pid}`
+        + `${snap.frontmost.title ? ` (${snap.frontmost.title})` : ''} holds the front, but the `
+        + `display shows ${total} element(s). Something is in front of the app, or the display is `
+        + 'not painting it. Which of those it is, is not knowable from here',
+      revive: true,
+    };
+  }
+  return { state: 'healthy', detail: `${total} element(s), sensors agree on ${snap.agreement ?? 'n/a'}`, revive: false };
+}
+
+export async function diagnose(deviceQuery, { options } = {}) {
+  const snap = await snapshot(deviceQuery, { options });
+  return { ...snap, verdict: classify(snap) };
+}