simframe 0.11.0 → 0.12.1

package/scripts/score-rulings.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Score a ruling population against the baselines that could embarrass it.
+//
+// Written **before** the population it first scored was finished, deliberately.
+// The previous attempt computed a `stillMs` threshold after seeing the answers,
+// on 14 samples of which 12 shared one label, and produced "100%" — a number
+// that was fitted, not measured. Fixing that afterwards is not possible: you
+// cannot un-see the data. So the split rule, the candidate thresholds and the
+// baselines are all fixed here in advance.
+//
+//   node scripts/score-rulings.mjs --device=<udid>
+//
+// What it will not do: pick the best threshold and report its score. It fits on
+// the first half and scores on the second, and prints both numbers so a gap
+// between them is visible as overfitting rather than hidden as success.
+import * as metrics from '../src/metrics.js';
+import { resolveDevice } from '../src/platform/index.js';
+
+const arg = (n, d) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${n}=`));
+  return hit ? hit.slice(n.length + 3) : d;
+};
+
+/** The fixtures, and the word each one's situation actually calls for. */
+const CORRECT = {
+  'the list is still loading; its rows arrive shortly after launch': 'wait',
+  'the detail screen is still fetching; its text arrives shortly': 'wait',
+  'the list arrives in waves and this row is in the last one': 'wait',
+  'Review is blocked until Species is filled in, and it is empty': 'stop',
+  'the first submit always fails and the second works, so waiting cannot help': 'stop',
+};
+
+/** `retry` and `wait` differ only in how long they settle, so both satisfy a wait. */
+const satisfies = (decision, want) =>
+  (want === 'wait' ? decision === 'wait' || decision === 'retry' : decision === want);
+
+const dev = await resolveDevice(arg('device'));
+const all = metrics.readSupervisions(dev.udid).filter((r) => CORRECT[r.expect]);
+// `--last=N` scores one batch rather than the whole log. Needed the first time
+// this ran: the log still held rulings from a deliberately skewed population,
+// so the balance read 19/35 and the baseline 65% when the batch actually under
+// test was 16/16. Mixing a known-bad population into the denominator is the
+// same error as before wearing a different hat.
+const lastN = Number(arg('last', 0));
+const rows = lastN > 0 ? all.slice(-lastN) : all;
+if (rows.length < 8) {
+  console.error(`only ${rows.length} labelled ruling(s) — run scripts/collect-rulings.mjs first`);
+  process.exit(2);
+}
+
+const want = (r) => CORRECT[r.expect];
+const counts = rows.reduce((a, r) => ({ ...a, [want(r)]: (a[want(r)] ?? 0) + 1 }), {});
+const commonest = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+const baseline = commonest[1] / rows.length;
+
+console.log(`${rows.length} labelled rulings on ${dev.name}`);
+console.log(`balance: ${JSON.stringify(counts)}`);
+console.log(`majority-class baseline: always "${commonest[0]}" scores ${(100 * baseline).toFixed(0)}%`);
+if (baseline > 0.65) {
+  console.log('\nSKEWED — any accuracy below is mostly a fact about the fixture set.');
+}
+
+const acc = (rs, predict) => rs.filter((r) => satisfies(predict(r), want(r))).length / (rs.length || 1);
+const pct = (x) => `${(100 * x).toFixed(0)}%`;
+
+console.log(`\n${'the model'.padEnd(30)} ${pct(acc(rows, (r) => r.decision))}`);
+console.log(`${`always "${commonest[0]}"`.padEnd(30)} ${pct(baseline)}`);
+
+// --- the stillMs rule, fitted on one half and scored on the other.
+//
+// Split by *recording order* rather than at random or by fixture, because the
+// alternative is choosing a split, and choosing is the thing that went wrong.
+const half = Math.floor(rows.length / 2);
+const fit = rows.slice(0, half);
+const held = rows.slice(half);
+const CANDIDATES = [1000, 1500, 2000, 2500, 3000, 4000, 5000, 6000, 7000];
+const rule = (t) => (r) => ((r.still_ms ?? 0) > t ? 'stop' : 'wait');
+
+let best = null;
+for (const t of CANDIDATES) {
+  const a = acc(fit, rule(t));
+  if (!best || a > best.a) best = { t, a };
+}
+console.log(`\nstillMs threshold, fitted on the first ${fit.length} and scored on the last ${held.length}:`);
+console.log(`  chosen on the fit half:  > ${best.t}ms  (${pct(best.a)} there)`);
+console.log(`  ${'on the held-out half:'.padEnd(24)} ${pct(acc(held, rule(best.t)))}`);
+console.log(`  ${'the model, same half:'.padEnd(24)} ${pct(acc(held, (r) => r.decision))}`);
+console.log('\nA rule that scores far better on the fit half than the held-out half was');
+console.log('fitted to noise. That gap is the number this script exists to print.');
+
+// --- the direction of the errors, which does not depend on the balance at all.
+const wrong = rows.filter((r) => !satisfies(r.decision, want(r)));
+const dirs = wrong.reduce((a, r) => {
+  const k = `said "${r.decision}" where "${want(r)}" was right`;
+  return { ...a, [k]: (a[k] ?? 0) + 1 };
+}, {});
+console.log(`\n${wrong.length} error(s) of ${rows.length}:`);
+for (const [k, n] of Object.entries(dirs).sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(3)}x ${k}`);
+if (Object.keys(dirs).length === 1 && wrong.length > 2) {
+  console.log('\nAll errors in one direction. A one-directional bias is what an abstain');
+  console.log('token addresses (DEFERRED 100), whatever the headline accuracy says.');
+}
+
+const lat = rows.map((r) => r.latency_ms).filter(Number.isFinite).sort((a, b) => a - b);
+if (lat.length) console.log(`\nmedian judgement latency: ${lat[lat.length >> 1]}ms`);
+const timed = rows.filter((r) => Number.isFinite(r.edge_p95_ms)).length;
+console.log(`edges the graph had timed: ${timed}/${rows.length}`);

package/scripts/soak-capture.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// How long can this device be driven before capture wedges?
+//
+// The wedge is the thing standing between us and a ruling population: the
+// display stops rendering after a few minutes of hard driving, `simctl
+// screenshot` fails too, both of the daemon's recoveries fail, and only a
+// device restart cures it. Three times in one afternoon.
+//
+// A leak was found in our own code on 2026-09-12 — damage-callback registration
+// was not idempotent, and the recovery loop called it on every attempt, so one
+// log's 670 port re-resolves meant up to 670 live callbacks on one port, each
+// invoked per redraw. That is a real leak with a plausible path to saturating
+// the display service, and it is **not proof** that it is the cause. This is
+// how we find out: drive until it dies, and report how long that took.
+//
+//   node scripts/soak-capture.mjs --device=<udid> --minutes=25
+//
+// A number to compare against, not a pass/fail. Before the fix, the device
+// wedged roughly every 10-20 minutes of this kind of work.
+import * as actions from '../src/actions.js';
+import * as api from '../src/index.js';
+import * as store from '../src/store.js';
+
+const arg = (n, d) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${n}=`));
+  return hit ? hit.slice(n.length + 3) : d;
+};
+const device = arg('device');
+const minutes = Number(arg('minutes', 20));
+const BUNDLE = 'com.example.simframetestbed';
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})   budget: ${minutes} minutes`);
+
+const started = Date.now();
+const deadline = started + minutes * 60_000;
+let laps = 0;
+let reads = 0;
+const elapsed = () => ((Date.now() - started) / 60_000).toFixed(1);
+
+// A lap is deliberately the kind of work that provokes it: launching, moving
+// between screens, and a cold read on each — not idling with a poll.
+const LAP = [
+  [{ launch: { value: BUNDLE, relaunch: true } }, { pause: 2500 }],
+  [{ tap: 'Forms, tab, 2 of 3' }, { pause: 800 }],
+  [{ tap: 'Long form' }, { pause: 900 }],
+  [{ scroll: 'down' }, { pause: 500 }],
+  [{ scroll: 'down' }, { pause: 500 }],
+  [{ tap: 'Plants, tab, 1 of 3' }, { pause: 900 }],
+  [{ tap: 'Diagnostics, tab, 3 of 3' }, { pause: 900 }],
+];
+
+while (Date.now() < deadline) {
+  for (const steps of LAP) {
+    try {
+      await actions.runScript(device, { steps, verify: false, options: { supervisor: 'none' } });
+    } catch { /* a failed step is not the subject; a dead display is */ }
+    try {
+      await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      reads += 1;
+    } catch (err) {
+      console.log(`\nWEDGED after ${elapsed()} minutes, ${laps} laps, ${reads} cold reads`);
+      console.log(`  ${String(err.message).split('\n')[0]}`);
+      const health = store.captureHealth(dev.udid);
+      if (health) console.log(`  captureHealth: ${JSON.stringify(health)}`);
+      process.exit(1);
+    }
+  }
+  laps += 1;
+  if (laps % 5 === 0) process.stdout.write(`  ${elapsed()}m  ${laps} laps  ${reads} reads  still alive\n`);
+}
+console.log(`\nSURVIVED ${minutes} minutes: ${laps} laps, ${reads} cold reads, no wedge`);

package/skills/simframe/SKILL.md

@@ -230,7 +230,10 @@ Measured against the same screen as an image: **~460 tokens of text versus
 image path degrades to base64-as-text. The text also says what is *tappable*
 and where, which an image does not.
 
-The numbers are selectors. Whatever `ui` calls `#3`, you can tap as `#3`.
+The numbers are selectors, and so are the labels beside them. Act by **name** —
+whatever `ui` calls `Weekly digest`, you can tap as `"Weekly digest"`. A `#3`
+is exact but only until the screen moves; see Selectors below for why that
+order is a correction rather than a preference.
 
 **Reach for an image only when the text genuinely cannot answer the question:**
 visual layout, colour, spacing, an animation, or something neither the
@@ -246,7 +249,7 @@ a baseline captured *before* it, so steps cannot race the UI.
 cat > /tmp/flow.json <<'JSON'
 [{"tap": "Inbox tab"},
  {"assert": {"value": "Weekly digest", "is": "visible"}},
- {"tap": "#3"},
+ {"tap": "Weekly digest"},
  {"type": {"into": "Reply", "text": "on it"}},
  {"scrollTo": "Send"},
  {"tap": "Send"},
@@ -312,6 +315,9 @@ the next call should change.
 | `#N cannot be trusted here — … this is a different screen` | the screen really did change. Read it again |
 | `autoSettle was off, so the map below was read without waiting` | the map may describe the screen *before* the last action landed |
 | `"iPhone 17 Pro" names more than one booted device` | a name cannot identify which device answered. Pass `device` with a UDID |
+| `frame 2.5s old` | the map was read from a frame that old. Usually fine after a deliberate pause; worth noticing if you expected to have just acted |
+| `WARNING this frame is Ns old — … a description of the past` | the screen may have moved on entirely. **Pass `refresh`** before believing any element below it. Reported from the field against 0.11.0: a complete 20-element map of a screen the app was not on, with nothing saying so |
+| `capture is wedged and both recoveries are spent` | the simulator has stopped rendering and neither of simframe's recoveries helped. Run `simframe revive --device=<udid>`; nothing else will work until you do |
 
 ## Every step is verified, and the verdict means something
 
@@ -388,8 +394,19 @@ as one call adds one exchange to the context instead of twelve.
 ```bash
 simframe doctor           # capture engine, input driver, a11y, OCR — each honestly
 simframe doctor --strict  # any degraded layer is a non-zero exit
+simframe input reset      # rebuild the HID session, without restarting anything
+simframe revive           # power-cycle a device that has stopped rendering
 ```
 
+**If capture has wedged**, `doctor` says so and nothing below it will work. A
+simulator driven hard for several minutes can stop rendering — `simctl
+screenshot` fails too, so it is the device and not simframe's view of it — and
+the daemon tries two recoveries, reports the state, and stops there. `simframe
+revive` does the restart in the order that matters and confirms frames are
+flowing again afterwards. It is a command rather than a behaviour on purpose:
+a capture loop that rebooted the device it was watching would be a tool
+reaching for the mains.
+
 simframe falls back when it must — the simctl capture loop instead of the
 daemon, idb instead of the in-process input and accessibility paths — but it
 never falls back quietly. If
@@ -405,6 +422,7 @@ simframe recall             # what happened in the last ~60s, as text
 simframe strip              # recent frames tiled into one image, for an animation
 simframe find "the save button"   # resolve an intent without acting on it
 simframe wait --mode=settle       # block until the screen stops reacting
+simframe supervisions             # what the local supervisor decided, and what came of it
 ```
 
 `recall` matters more than it looks: if you look up and the screen is already

package/src/actions.js

@@ -209,6 +209,62 @@ export async function runScript(
       /* instrumentation must not be able to fail a flow it is only watching */
     }
   };
+  /**
+   * What the caller is shown for each outcome, keyed by what the log stores.
+   *
+   * Two vocabularies on purpose. The log wants tokens that will still parse in
+   * six months; the result and the CLI line want English, and a test already
+   * pins those words. Mapping them here is what stops the two drifting.
+   */
+  const SHOWN = {
+    recovered: 'recovered',
+    still_failed: 'still failed',
+    stopped: 'stopped the run',
+    no_ruling: 'no ruling',
+  };
+  /**
+   * Record one ruling, in memory for the caller and on disk for the analysis.
+   *
+   * One helper rather than four call sites because the two had already drifted
+   * apart once — `from` was on the `stop` push and on none of the others, so a
+   * rule-sourced wait was indistinguishable from a model-sourced one in the
+   * only place that reported them. A ruling that reaches the caller and not the
+   * log is the state item 101a exists to end: three rulings had ever existed
+   * anywhere, and 101, 106 and 96 are all waiting on a population.
+   */
+  const noteRuling = (index, ruling, outcome, { step, expect, failure, why } = {}) => {
+    const shown = SHOWN[outcome] ?? outcome;
+    const unanswered = why?.kind
+      ? `the supervisor did not answer: ${why.kind}`
+      : 'the supervisor did not answer';
+    supervisions.push({
+      index,
+      decision: ruling?.decision ?? 'unavailable',
+      reason: ruling?.reason ?? unanswered,
+      from: ruling?.from,
+      outcome: shown,
+    });
+    try {
+      metrics.recordSupervision(udid, {
+        index,
+        step: step ? graph.actionSignature(step) : ruling?.context?.action ?? null,
+        edge: ruling?.context?.edge ?? null,
+        screen: ruling?.context?.screen ?? null,
+        decision: ruling?.decision ?? 'unavailable',
+        from: ruling?.from ?? (ruling ? 'model' : 'none'),
+        reason: ruling?.reason ?? unanswered,
+        ms: ruling?.ms,
+        stillMs: ruling?.context?.stillMs,
+        p95: ruling?.context?.p95,
+        samples: ruling?.context?.samples,
+        expect,
+        failure,
+        outcome,
+      });
+    } catch {
+      /* instrumentation must not be able to fail a flow it is only watching */
+    }
+  };
 
   const needsInput = steps.some((s) => ACTION_STEPS.has(normalizeStep(s).action));
   if (needsInput) {
@@ -309,8 +365,15 @@ export async function runScript(
         // Ask the supervisor before anything is abandoned. It sits behind the
         // hands and in front of the reasoner: first responder, not
         // decision-maker, and its whole vocabulary is wait/retry/stop.
+        // Why a consultation produced nothing, for the log. Every failure used
+        // to arrive as "the supervisor did not answer" — a timeout, a guardrail
+        // refusal and a model that was never installed reading identically.
+        const why = {};
         const ruling = await superviseFailure(deviceQuery, {
-          goal: supervise ?? flowName, step, expected: step.expect, err, options,
+          goal: supervise ?? flowName, step, expected: step.expect, err, options, udid, detail: why,
+        });
+        const ruled = (outcome) => noteRuling(i, ruling, outcome, {
+          step, expect: step.expect, failure: err.message, why,
         });
         if (ruling?.decision === 'wait' || ruling?.decision === 'retry') {
           // Both wait and retry settle first, differing only in how long.
@@ -332,10 +395,10 @@ export async function runScript(
           try {
             detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
             detail += ` [the local supervisor said ${ruling.decision}; it worked on the second attempt]`;
-            supervisions.push({ index: i, decision: ruling.decision, reason: ruling.reason, outcome: 'recovered' });
+            ruled('recovered');
             continue;
           } catch (again) {
-            supervisions.push({ index: i, decision: ruling.decision, reason: ruling.reason, outcome: 'still failed' });
+            ruled('still_failed');
             err = again;
           }
         } else if (!ruling && supervisor.requested(options)) {
@@ -345,10 +408,12 @@ export async function runScript(
           // model healthy. The reporter's own words — *"had I run flow 2 alone
           // I would have reported the supervisor makes no difference without
           // realising it had never run"*.
-          supervisions.push({ index: i, decision: 'unavailable', reason: 'the supervisor did not answer', outcome: 'no ruling' });
-          err.message += ' — the local supervisor was consulted and did not answer, so this failure was not judged.';
+          ruled('no_ruling');
+          err.message += ' — the local supervisor was consulted and did not answer'
+            + (why.kind ? ` (${why.kind})` : '')
+            + ', so this failure was not judged.';
         } else if (ruling?.decision === 'stop') {
-          supervisions.push({ index: i, decision: 'stop', reason: ruling.reason, from: ruling.from, outcome: 'stopped the run' });
+          ruled('stopped');
           const remaining = steps.slice(i);
           err.message += ` — the local supervisor stopped the run here.`
             + ` ${remaining.length} step(s) were not attempted.`
@@ -1123,14 +1188,34 @@ const SUPERVISOR_RETRY_MS = 900;
 /** A scroll moves at once or not at all; it does not need a transition's budget. */
 const SCROLL_SETTLE_MS = 800;
 
-async function superviseFailure(deviceQuery, { goal, step, expected, err, options }) {
+async function superviseFailure(deviceQuery, { goal, step, expected, err, options, udid, detail }) {
   if (!supervisor.requested(options)) return null;
+  // The action half of the edge is free — the step is in hand — so a rule-sourced
+  // ruling still records which action it was about even though it never reads
+  // the screen. Deliberately no `screenMap` call on this path: the rule exists
+  // to answer without one, and paying for a read to make the log prettier would
+  // slow the fast path to improve the bookkeeping.
+  const action = graph.actionSignature(step);
   const settled = deterministicRuling(err);
-  if (settled) return { decision: settled.decision, reason: settled.why, from: 'rule' };
+  if (settled) {
+    return {
+      decision: settled.decision, reason: settled.why, from: 'rule',
+      context: { action, edge: action, screen: null, stillMs: null, p95: null, samples: null },
+    };
+  }
   try {
     const map = await view.screenMap(deviceQuery, { options, refresh: false });
     const stillMs = map.identity?.state?.motion?.stillForMs;
-    return await supervisor.judge({
+    const screen = map.identity?.hash ?? null;
+    // What the graph knew about this edge at the moment of the ruling. Read
+    // here and not at analysis time on purpose: the graph keeps learning, so a
+    // p95 looked up next week is not the number this ruling was competing
+    // with, and item 101 asks exactly "would a p95 lookup have got this right".
+    let timing = null;
+    try {
+      timing = udid && map.identity ? graph.timingFor(udid, map.identity, step) : null;
+    } catch { /* an unknown edge is a fact about the graph, not a failure here */ }
+    const ruling = await supervisor.judge({
       goal,
       step: `${step.action} ${JSON.stringify(String(step.value ?? step.target ?? step.into ?? step.seek ?? '').slice(0, 60))}`,
       expected,
@@ -1139,7 +1224,21 @@ async function superviseFailure(deviceQuery, { goal, step, expected, err, option
       stillMs,
       note: stillFillingIn(map.identity?.entry),
       options,
+      detail,
     });
+    if (!ruling) return null;
+    return {
+      ...ruling,
+      from: ruling.from ?? 'model',
+      context: {
+        action,
+        edge: screen ? `${String(screen).slice(0, 12)}:${action}` : action,
+        screen,
+        stillMs,
+        p95: timing?.p95 ?? null,
+        samples: timing?.samples ?? null,
+      },
+    };
   } catch {
     return null;
   }

package/src/cli.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { runDaemon, DEFAULTS } from './daemon.js';
-import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, screenshot, toolchainChecks } from './platform/index.js';
+import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, restartDevice, screenshot, toolchainChecks } from './platform/index.js';
 import * as actions from './actions.js';
 import * as analyze from './analyze.js';
 import * as api from './index.js';
@@ -47,6 +47,8 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe baseline list             recorded runs per flow, and what is committed
   simframe hpi     [device]          Human Parity Index, per flow and overall
   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
                                      (--session=<id> narrows to one agent; the
                                      ids are listed in the output. SIMFRAME_SESSION
                                      names one, but only at process start — an
@@ -56,10 +58,12 @@ const USAGE = `simframe — always-warm iOS Simulator frames
                                      (--strict, or SIMFRAME_STRICT=1, makes any
                                       degraded layer a non-zero exit)
 
-Selectors — anywhere a control is named
-  #3            the number \`simframe ui\` gave it. Cheapest, unambiguous.
-  "Save"        a label or a phrase, resolved by intent (verbs, typos, synonyms)
-  @120,400      raw point coordinates
+Selectors — anywhere a control is named, best first
+  "Save"        a label or a phrase, resolved by intent (verbs, typos, synonyms,
+                icon-only controls by their common name). Start here.
+  #3            the number \`simframe ui\` gave it. Exact, but only inside the
+                round trip that numbered it — the screen moves and it does not.
+  @120,400      raw point coordinates. Last resort: it cannot tell you it missed.
 
 Measuring against a human — the Human Parity Index
 
@@ -378,6 +382,51 @@ async function main() {
       return;
     }
 
+    // The power cycle, when the narrow remedies are spent.
+    //
+    // Deliberately a command and not a behaviour. The capture loop tries two
+    // things — re-resolve the display port, then rebind the device — and then
+    // reports `stalled` and stops, because a capture loop that rebooted the
+    // device it was watching would be a tool reaching for the mains when a
+    // reading looks wrong. Restarting is the operator's call.
+    //
+    // But it was the operator's call *and* their four commands, remembered from
+    // a handoff note: stop the daemon, shut the device down, boot it and wait,
+    // start capture, rebuild the HID session. Done by hand three times in one
+    // afternoon, in that order, because any other order leaves a daemon holding
+    // a dead device. So the tool knows the order now; the decision is still
+    // yours.
+    case 'revive': {
+      const dev = await resolveDevice(device);
+      const say = (line) => { if (!flags.json) console.log(line); };
+      const steps = [];
+      const did = async (what, fn) => {
+        try { await fn(); steps.push({ step: what, ok: true }); say(`  ok   ${what}`); } catch (err) {
+          steps.push({ step: what, ok: false, error: err.message });
+          say(`  ..   ${what} — ${err.message.split('\n')[0]}`);
+        }
+      };
+      say(`reviving ${dev.name}`);
+      // Forced: the point of this command is that the device is wedged, so
+      // something is certainly still holding it.
+      await did('stopped the daemon', async () => { api.stopDaemon(dev.udid, { force: true }); });
+      // Through the boundary, which is the whole point of the boundary: the
+      // first version of this shelled out to `xcrun` from here and the test
+      // that forbids it failed immediately, correctly.
+      await did('restarted the device, and waited for the boot to finish',
+        () => restartDevice(dev.udid));
+      await did('started capture', () => api.ensureDaemon(dev.udid));
+      await did('rebuilt the HID session', () => input.resetSession(dev.udid));
+      const health = await api.getState(dev.udid).then((s) => s?.state ?? null).catch(() => null);
+      const alive = Boolean(health?.hash);
+      emit(flags, { ok: alive, device: dev.udid, steps }, alive
+        ? `\n${dev.name} is producing frames again`
+        : `\n${dev.name} is still not producing frames. This is past what simframe can do —`
+          + ' check Simulator.app is not showing an error, and see docs/DEFERRED.md item 95.');
+      if (!alive) process.exitCode = 1;
+      return;
+    }
+
     case 'status': {
       const udids = device
         ? [(await resolveDevice(device)).udid]
@@ -1027,6 +1076,37 @@ async function main() {
       return;
     }
 
+    case 'supervisions': {
+      const dev = await resolveDevice(flags.device);
+      const records = metrics.readSupervisions(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      const b = metrics.supervisionBreakdown(records);
+      if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify({ ...b, records }, null, 2)}\n`);
+      emit(flags, { ...b, records: flags.verbose ? records : undefined }, [
+        `${b.total} supervisor ruling${b.total === 1 ? '' : 's'} on ${dev.name}`,
+        b.total ? '' : 'Nothing has been judged on this device yet. The supervisor is off unless'
+          + ' SIMFRAME_SUPERVISOR=apple, and a ruling is only recorded when a step actually fails.',
+        ...Object.entries(b.decision_to_outcome)
+          .sort((a, c) => c[1] - a[1])
+          .map(([k, n]) => `  ${k.padEnd(28)} ${String(n).padStart(4)}`),
+        b.total ? '' : null,
+        b.total ? `sourced: ${Object.entries(b.by_from).map(([k, n]) => `${k} ${n}`).join(', ')}` : null,
+        b.median_latency_ms != null ? `median latency: ${b.median_latency_ms}ms` : null,
+        // Said out loud, because the first version of item 101 claimed its
+        // measurement ran "on logs we already have" when nothing persisted a
+        // ruling at all. This line is what stops that claim being made twice.
+        b.total
+          ? `edges the graph had timed: ${b.p95_known}/${b.total}`
+            + (b.p95_unknown
+              ? ` — ${b.p95_unknown} ruling(s) are on edges with no p95, so they cannot take part in 101's comparison`
+              : '')
+          : null,
+        b.sessions.length > 1
+          ? `WARNING ${b.sessions.length} sessions are pooled here; two agents on one device write one file`
+          : null,
+      ].filter((l) => l !== null).join('\n'));
+      break;
+    }
+
     case 'escalations': {
       const dev = await resolveDevice(flags.device);
       const records = metrics.readEscalations(dev.udid, { limit: flags.last ? num(flags.last) : undefined });

package/src/fingerprint.js

@@ -48,8 +48,32 @@ import * as regions from './regions.js';
  *     extends upward while the rows above keep being key-shaped, which page
  *     content is not. Any screen fingerprinted with a keyboard up hashes
  *     differently, so the stored graph and maps must go again.
+ *
+ * 7 — a screen whose own name is an iOS **large title** had no name at all in
+ *     its identity. Chrome labels are the only text these tokens keep, and a
+ *     large title is drawn tight against the content it heads — 79 pt of inset
+ *     above it and 5.3 pt below, against a boundary bar of 66.5 — so the top
+ *     chrome detector, which looks for the gap *beneath* a bar, never found it
+ *     and the title was discarded as content. Measured on the Settings root in
+ *     both sensor modes: **0 named tokens**, and the same for Contacts and
+ *     Reminders. On a hosted runner two sparse nameless readings then matched
+ *     exactly and one hash stood for two different screens. `regions.bands`
+ *     now finds a large title by the inset above it; every affected screen
+ *     hashes differently, so stored graphs and maps go again.
+ *
+ * 8 — the same rule, keyed on the wrong thing. Its "is this a real inset"
+ *     test compared the gap above the title against the screen's **median row
+ *     gap**, so whether a system-drawn title counted as chrome depended on how
+ *     many rows happened to sit below it. Caught on the React Native testbed's
+ *     first day, with two screens of one app: a list of 24 rows has a median
+ *     gap of 0 and the rule fired, a list of 4 above a tab bar has a median gap
+ *     of **414** and it did not. Same title, same 62.9pt inset, opposite
+ *     answers — so one screen carried a name and the other did not, and the
+ *     graph merged them. Both bounds are absolute now. Screens that were
+ *     missed at 7 hash differently at 8, and unlike a stale hash that matches
+ *     nothing, these matched the *wrong* thing.
  */
-export const TOKEN_RULES_VERSION = 6;
+export const TOKEN_RULES_VERSION = 8;
 
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;

package/src/graph.js

@@ -258,6 +258,28 @@ export function nearestScreen(udid, screen, { threshold = SIMILARITY_THRESHOLD }
   for (const node of nodes) {
     for (const f of fingerprintsOf(node)) {
       if (!f.tokens?.length) continue;
+      // A screen that says it is called something else is not this screen.
+      //
+      // Similarity weighs every token equally, and a chrome label is not an
+      // equal token — it is the only text in a fingerprint and the only thing
+      // that distinguishes two screens of the same shape. `fingerprint.js` has
+      // said so in a comment since it was written: "two list screens with
+      // identical structure differ by their title, and nothing else says so".
+      // Nothing enforced it.
+      //
+      // Measured on the RN testbed, which is what found this: a list of plants
+      // and a list of forms, each a large title over full-width rows above a
+      // tab bar, scored **0.50** against a 0.36 threshold and became one node.
+      // Both were correctly named by then; the name was simply outvoted, being
+      // one token of a union of six. The graph then offered one screen's
+      // controls on the other, which is the failure `verify` exists to stop.
+      //
+      // Both sides must actually carry names for this to apply. A reading whose
+      // tree did not answer has no names through no fault of the screen's, and
+      // the two sensors are already known to disagree about 0.33-0.47 of a
+      // token set — so "one has names, the other does not" is a fact about the
+      // sensors and must not be read as a fact about identity.
+      if (disagreeOnName(f.tokens, key.tokens)) continue;
       const s = fingerprint.similarity(f.tokens, key.tokens);
       if (s > bestSimilarity) {
         bestSimilarity = s;
@@ -268,6 +290,31 @@ export function nearestScreen(udid, screen, { threshold = SIMILARITY_THRESHOLD }
   return best && bestSimilarity >= threshold ? { node: best, similarity: bestSimilarity } : null;
 }
 
+/** The chrome labels in a token set — the only text a fingerprint keeps. */
+function namesIn(tokens) {
+  const out = new Set();
+  for (const t of tokens ?? []) {
+    const open = t.indexOf('"');
+    if (open < 0) continue;
+    const close = t.lastIndexOf('"');
+    if (close > open) out.add(t.slice(open + 1, close));
+  }
+  return out;
+}
+
+/**
+ * Do these two readings name themselves, and name themselves differently?
+ *
+ * Only a positive disagreement counts. Silence on either side is not evidence.
+ */
+function disagreeOnName(a, b) {
+  const left = namesIn(a);
+  const right = namesIn(b);
+  if (!left.size || !right.size) return false;
+  for (const name of left) if (right.has(name)) return false;
+  return true;
+}
+
 /**
  * Teach a node that it also looks like this.
  *