simframe 0.16.0 → 0.18.0

package/README.md

@@ -172,6 +172,18 @@ selector that did not *resolve* and nothing else, because retrying from a screen
 you did not expect to be on is a second guess. A destructive-looking label is
 refused as a substitute even if you list it.
 
+**Steps that may legitimately have nothing to act on.** `{"tap": "Not Now",
+"optional": true}` is skipped when nothing matches and runs normally when
+something does. It exists because the opposite cost real time: a batch that
+included a dismissal for a first-launch sheet lost **six correct steps** on the
+next run because the sheet *did not appear*. A nag screen, a permission prompt,
+a "What's New" or a cold-start splash otherwise makes a flow unbatchable, which
+is the expensive outcome — a call per step instead of a call per flow. Only a
+selector that resolved to **nothing** is absorbed: a target that is on screen
+twice is ambiguous, not absent, and must still verify. Skipped steps are
+reported, because "the sheet was gone" and "the sheet was dismissed" are
+different facts.
+
 **`{"seek": "change username", "budget": 6}`** opens containers, checks, and
 comes back, depth first, inside a hard budget. It **acts** — opening a door
 changes state — and it refuses to open anything that commits, abandons or
@@ -400,7 +412,7 @@ steer the model is a tool surface the model uses wrong.
 | `sim_do` | **The main tool.** A whole flow in one call — tap, type, scroll, wait, assert — each step settling before the next and verified against what it did last time. |
 | `sim_state` | The cheapest question there is: has anything changed **since your last look**, and which regions moved. |
 | `sim_goto` | Walk to a screen simframe has been to before, planning the route through remembered transitions. |
-| `sim_flow_run` | Replay a flow that verified end to end. |
+| `sim_flow_run` | Replay a saved flow — **zero model calls**, which is the only path to human wall clock. A first traversal saves as *provisional*; one replay in which every step passed confirms it. A run with a contradicted step, a failed step, or one that never reached its last step is refused and says which. |
 | `sim_find` | Resolve an intent to one control, without acting on it. |
 | `sim_tap` · `sim_type_into` · `sim_scroll_to` · `sim_wait_for` · `sim_assert` | Single actions, for when you genuinely only have one step. Each is one `sim_do` step underneath. |
 | `sim_launch` · `sim_open_url` · `sim_permission` | Launch with arguments and environment; open a deep link; grant a privacy permission instead of tapping a system alert. A launch is **confirmed to have reached the front**, by comparing the pid `simctl` started against the pid the device reports as frontmost — so *"the process started"* is no longer reported as *"the app is on screen"*. |
@@ -710,16 +722,59 @@ feels, and it took two field reports to see it. Per-step wall clock is
 (model round trip + simframe work × n) / n        for n steps in one call
 ```
 
-| | per step |
-| --- | --- |
-| a human tester, measured | **1.95 s** |
-| **a saved flow replayed — zero model calls** | **1.98 s** |
-| simframe's own work inside a batch | **~1.7 s** |
-| a batch of 4 steps, one model call | ~6.7 s |
-| a batch of 2 steps | ~11.7 s |
-| one model call per step | ~21.7 s |
-
-**A replayed flow runs at human speed**, and simframe's own work already does.
+**Compare like with like, which this table used not to.** A human tester's
+1.95 s per step is the *whole* loop — look at the screen, decide what to do,
+do it. Any row that does not include a decision is not comparable to it.
+
+| | perceives | decides | acts | per step |
+| --- | --- | --- | --- | --- |
+| **a human tester, measured** | yes | yes | yes | **1.95 s** |
+| **simframe, batch of 2 — the recorded median** | yes | yes | yes | **~11.7 s** |
+| simframe, batch of 4 | yes | yes | yes | ~6.7 s |
+| simframe, one model call per step | yes | yes | yes | ~21.7 s |
+| — simframe's mechanical half alone | yes | **no** | yes | ~1.7 s |
+| — a saved flow replayed | yes | **no** | yes | 1.98 s |
+
+**The only like-for-like comparison is 1.95 s against ~11.7 s: about six times
+a human**, and about eleven times when a failure forces one model call per step.
+
+The two indented rows are the ones this README used to lead with, and both are
+category errors when set against 1.95 s. The 1.7 s is simframe with the thinking
+taken out — the thinking is the model round trip, which is most of the clock.
+And a replay *decides nothing*: it is a recording being played back, so its fair
+counterpart is a human repeating a flow they have memorised, who would be well
+under 1.95 s. Replay against a human working something out for the first time is
+a rehearsal measured against a first attempt.
+
+What the two rows do establish, and it is the finding that reordered this
+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
@@ -840,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
@@ -864,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.16.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/ci-memory.mjs

@@ -646,12 +646,25 @@ console.log('\n--- what may be saved, and what may not ---');
 // evidence for it. Checked against whatever the run actually produced rather
 // than assuming a shape, as before.
 const attempt = await jsonRetry(['do', LOOP, `--save=${FLOW_NAME}`], { allowFail: true });
+//
+// Three outcomes, not two. The missing one is a step that ran and *failed*: a
+// failing step stops the batch, so a failure on the last step leaves
+// `ranSteps === steps.length` and the run reads as complete. A peer watched
+// `FLOW FAILED — 4 ok, 1 failed (of 5)` save itself. This branch is also the
+// one that goes stale: yesterday the save contract was replaced, the unit test
+// was updated, and this file was left asserting the old rule — so the three
+// cases are enumerated here explicitly rather than left as an `else`.
 const contradicted = attempt.results.some((r) => /^unexpected/.test(r.verification?.verdict ?? ''));
+const anyFailed = attempt.results.some((r) => !r.ok);
 const clean = attempt.results.every((r) => !r.verification || r.verification.verdict === 'ok');
 if (contradicted) {
   check(attempt.saved?.ok === false && attempt.saved?.reason === 'contradicted-steps',
     'a flow with a contradicted step is refused, not quietly saved',
     `${attempt.saved?.reason} (${(attempt.saved?.verdicts ?? []).join(', ')})`);
+} else if (anyFailed) {
+  check(attempt.saved?.ok === false && attempt.saved?.reason === 'failed-steps',
+    'a flow with a step that ran and failed is refused, not quietly saved',
+    `${attempt.saved?.reason} (failed step ${(attempt.saved?.failed ?? []).join(', ')})`);
 } else {
   check(attempt.saved?.ok === true, 'a first traversal is recordable',
     `${attempt.saved?.steps} steps`);
@@ -676,12 +689,21 @@ if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.sa
   // state nothing ever leaves: a clean replay is the confirmation a first
   // traversal could not give. Only asserted when the replay actually ran to
   // the end — a partial replay promotes nothing, deliberately.
+  const after = await jsonRetry(['flow', 'list']);
+  const entry = after.find((f) => f.name === FLOW_NAME);
   if (replayed.ok) {
-    const after = await jsonRetry(['flow', 'list']);
-    const entry = after.find((f) => f.name === FLOW_NAME);
     check(entry && !entry.provisional,
       'and a clean replay confirms a provisional flow',
       `provisional=${entry?.provisional ?? 'gone'}`);
+  } else {
+    // The other direction, and it is the one that was silently wrong: promotion
+    // keyed on `ranSteps === steps.length`, which a failure on the *last* step
+    // satisfies. Both of a peer's saved flows were marked confirmed by replays
+    // that failed. A confirmation that a failing replay can grant is not a
+    // confirmation, so the negative case has to be checked too.
+    check(entry?.provisional === true,
+      'and a replay that failed does NOT confirm the flow it just disproved',
+      `ok=${replayed.ok}, provisional=${entry?.provisional}`);
   }
   const unknown = await cli(['flow', 'run', 'no-such-flow'], { expectFail: true });
   check(/no flow/i.test(unknown), 'an unknown flow name is refused with what is known');

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

@@ -346,6 +346,16 @@ export async function runScript(
   // the caller returns to Claude is rendered from this, so describing the end
   // state costs nothing beyond the verification pass the flow already ran.
   let endScreen = null;
+  // Where this run began, so a flow saved from it can say what it assumes.
+  //
+  // Null when the first step does not depend on where we were — see
+  // `resetsTheScreen`.
+  //
+  // It was recorded as `null` on every flow 0.16.0 saved, which a peer caught:
+  // "replay never checks it is starting where it was recorded". Reading it is
+  // free — the first step computes the identity anyway — and it is a fact the
+  // recording had and discarded.
+  let startScreen = null;
   // At most one recovery per run. Pressing home while already on the springboard
   // moves nothing and is not a failure, so an unbounded retry would rebuild the
   // session and press again on every such step for no reason.
@@ -393,6 +403,9 @@ export async function runScript(
       ? (carriedScreen ?? await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs, confirmNovel }))
       : null;
     carriedScreen = null;
+    if (i === 0 && !resetsTheScreen(step)) {
+      startScreen = beforeScreen ? { hash: beforeScreen.hash ?? null, tokens: beforeScreen.tokens ?? null } : null;
+    }
     // What this action did last time it was taken here, if ever.
     const prediction = verify && beforeScreen?.hash ? graph.predict(udid, beforeScreen, step) : null;
     try {
@@ -920,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
@@ -945,10 +970,42 @@ export async function runScript(
         break;
       }
     } catch (err) {
+      // A step that was allowed not to be there, and is not there.
+      //
+      // `or:` supplies alternative *selectors*; nothing could express "skip
+      // this if absent". So a batch crossing a first-launch nag, a permission
+      // prompt or a "What's New" could not be batched at all — the interstitial
+      // appears on run one and not on run two, the step fails, and every
+      // remaining step is discarded. A peer lost six correct steps because a
+      // sheet *did not* appear, and on the framing that every hard-fail
+      // dropping a caller back to single-stepping is a latency bug, that is the
+      // most expensive shape there is: ~20 s per step, for the rest of the plan.
+      //
+      // Deliberately narrow. Only `unknown_screen` — the selector resolved to
+      // nothing — absorbs. `ambiguous_intent` means the target *is* there,
+      // twice, and a step that is present must still verify; so must one that
+      // resolved and then failed. "Skip if absent" must not become "tap
+      // whatever is there".
+      if (step.optional && didNotResolve(err)) {
+        results.push({
+          index: i,
+          action: step.action,
+          ok: true,
+          skipped: true,
+          ms: Date.now() - stepStart,
+          detail: `skipped — optional, and ${JSON.stringify(String(goalOf(step) ?? step.action))} is not on this screen`,
+        });
+        continue;
+      }
       results.push({ index: i, action: step.action, ok: false, ms: Date.now() - stepStart, error: err.message });
       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,
@@ -1020,6 +1077,7 @@ export async function runScript(
     // navigate.saveFlow without the caller reassembling what it just ran.
     steps,
     flowId,
+    startScreen,
     endScreen,
     results,
     ok: !failed,
@@ -1462,6 +1520,53 @@ export function alternativesFor(step) {
   return list.map((v) => (typeof v === 'string' ? v : v?.value ?? v?.target ?? v?.label)).filter(Boolean);
 }
 
+/**
+ * Does this step make the screen we were on irrelevant?
+ *
+ * A flow that opens with `launch`, a deep link, or the home button does not
+ * assume anything about where it starts — it goes and puts the device
+ * somewhere. Recording a start screen for such a flow records where the device
+ * happened to be beforehand, which is noise, and then reports a mismatch on
+ * every replay that began anywhere else.
+ *
+ * Measured, not reasoned: a flow opening with `launch --relaunch` replayed
+ * perfectly and still printed "recorded starting on 8292b488, replayed from
+ * 39351dab", because the recording had followed a run that ended on Settings
+ * root and the replay followed one that ended on About. Most flows open with a
+ * launch, so that note would have fired on most correct replays — which is
+ * item 175's defect exactly, in a feature added the same day 175 was written up.
+ */
+export function resetsTheScreen(step = {}) {
+  if (step.action === 'launch' || step.action === 'openUrl') return true;
+  return step.action === 'button' && /^home$/i.test(String(step.value ?? '').trim());
+}
+
+/**
+ * Did this failure mean "the thing is not here", as opposed to any other way a
+ * step can fail? The one question `optional` is allowed to ask.
+ *
+ * **Not `reason === 'unknown_screen'`, which is what this said for one build and
+ * what made `optional` a no-op on every screen it was built for.** The tag at
+ * the throw site is chosen by whether the *screen* was recognised, not by
+ * whether the *target* was found: on a screen recalled from memory an absent
+ * target is tagged `ambiguous_intent` too. So a conditional interstitial on a
+ * well-known screen — the whole use case — never absorbed. Caught by running it
+ * against a device; the unit test exercised this predicate and passed, because
+ * it tested the predicate rather than the path.
+ *
+ * The distinction that actually exists is `ambiguous`, set only where something
+ * was found *several times over*, and the comment at that throw site had
+ * already written down why it matters: "more time cannot make a thing unique,
+ * and it can make an absent thing arrive." Absent is the case `optional` may
+ * skip; present-twice must still verify.
+ */
+const RESOLVE_REASONS = new Set(['unknown_screen', 'ambiguous_intent']);
+
+export function didNotResolve(err) {
+  const tagged = metrics.escalationOf(err);
+  return Boolean(tagged && RESOLVE_REASONS.has(tagged.reason) && !tagged.ambiguous);
+}
+
 export function mayRetryAfter(err) {
   const tagged = metrics.escalationOf(err);
   return Boolean(tagged && RESOLVE_FAILURES.has(tagged.reason));
@@ -3246,13 +3351,23 @@ export function settleEvidence(w) {
  */
 export function flowSummary(res, { withTime = true } = {}) {
   const time = withTime && Number.isFinite(res.totalMs) ? ` in ${res.totalMs}ms` : '';
-  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}`;
+  // A step that was allowed not to be there and was not there did not run, and
+  // saying so is the difference between "the nag screen was gone" and "the nag
+  // screen was dismissed". Same lesson as the denominator above: a count that
+  // quietly means two things is the defect.
+  const skipped = (res.results ?? []).filter((r) => r.skipped).length;
+  // After the time, in parentheses. Written inline before it, this read
+  // "skipped as absent in 3412ms" — which says the skipping took 3.4 seconds.
+  const skips = skipped
+    ? ` (${skipped} optional step${skipped === 1 ? '' : 's'} skipped as absent)`
+    : '';
+  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
   const failed = (res.results ?? []).filter((r) => r.ok === false).length || 1;
   const worked = Math.max(0, res.ranSteps - failed);
   const unattempted = Math.max(0, res.totalSteps - res.ranSteps);
   return `FLOW FAILED — ${worked} ok, ${failed} failed`
     + (unattempted ? `, ${unattempted} not attempted` : '')
-    + ` (of ${res.totalSteps})${time}`;
+    + ` (of ${res.totalSteps})${time}${skips}`;
 }
 
 /**

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
@@ -285,6 +287,20 @@ async function main() {
   // is a different machine and should say so rather than be guessed at.
   if (flags.readyTimeoutMs) options.readyTimeoutMs = num(flags.readyTimeoutMs);
 
+  // `--help` on any command, not only as the command.
+  //
+  // `simframe hpi --help` did the two worst things in sequence: without
+  // `--device` it demanded a device *before* printing help, and with one it
+  // ignored `--help` and ran the report. A flag that is ignored is worse than
+  // one that is rejected — it silently does something other than what was
+  // asked. (The general case, unrecognised flags being dropped everywhere
+  // rather than here, is filed separately; this is the one that was measured
+  // costing a round trip.)
+  if (flags.help || flags.h) {
+    process.stdout.write(USAGE);
+    return;
+  }
+
   switch (command) {
     case undefined:
     case '-h':
@@ -433,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]
@@ -977,6 +1013,9 @@ async function main() {
           return;
         }
         emit(flags, res, [
+          ...(res.startedElsewhere
+            ? [`NOTE: recorded starting on ${res.startedElsewhere.recorded}, replayed from ${res.startedElsewhere.here}`]
+            : []),
           ...(res.results ?? []).map(stepLine),
           actions.flowSummary(res, { withTime: false }),
         ]);
@@ -1236,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}`,
@@ -1248,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,
       ]);
@@ -1337,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