simframe 0.8.0 → 0.10.0

package/src/cli.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 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, toolchainChecks } from './platform/index.js';
+import { bootedDevices, capabilitiesFor, listDevices, PLATFORMS, resolveDevice, screenshot, toolchainChecks } from './platform/index.js';
 import * as actions from './actions.js';
+import * as analyze from './analyze.js';
 import * as api from './index.js';
 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 { decodePng } from './png.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -16,6 +21,7 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe start   [device]          start the capture loop in the background
   simframe stop    [device|--all]    stop the capture loop
   simframe status  [device]          show daemon and newest-frame status
+  simframe input   reset             rebuild the HID session (see doctor)
   simframe frame   [device]          write the newest frame to a file
   simframe state   [device]          print frame metadata and the change map
   simframe mark    [device]          print the current frame hash, to use as --since
@@ -36,6 +42,11 @@ const USAGE = `simframe — always-warm iOS Simulator frames
   simframe type    <text>            enter text (exact; uses the pasteboard)
   simframe keys    <text>            send key events instead (layout-dependent)
   simframe press   <button>          a hardware button, e.g. home
+  simframe baseline record <flow>    record a human performing a flow (see below)
+  simframe baseline summarize <flow> write the median/IQR baseline for it
+  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 devices                   list simulators
   simframe doctor                    check that this machine can capture
                                      (--strict, or SIMFRAME_STRICT=1, makes any
@@ -46,6 +57,21 @@ Selectors — anywhere a control is named
   "Save"        a label or a phrase, resolved by intent (verbs, typos, synonyms)
   @120,400      raw point coordinates
 
+Measuring against a human — the Human Parity Index
+
+  A flow's agent time is measured every time it runs; the human half has to be
+  recorded once, by a person, on the same simulator:
+
+    simframe baseline record settings-larger-text --device=<udid> --runs=5
+    simframe baseline summarize settings-larger-text
+    simframe hpi --device=<udid>
+
+  \`record\` puts the device on the home screen, waits for you to start, and
+  waits again for you to stop. Wall time is measured between those two; the
+  step count is derived from screen transitions, because a human tapping the
+  Simulator window leaves no HID log to read. Five runs is the recommendation
+  and three is the floor. The flows live in flows/hpi-suite.json.
+
 Options
   --device=<udid|name>   simulator to target (default: the booted one)
   --json                 machine-readable output — on every command
@@ -96,6 +122,7 @@ The reliable pattern around an action is:
 const VALUE_FLAGS = new Set([
   'ago', 'count', 'detail', 'device', 'durationMs', 'engine', 'filter', 'fps', 'index', 'maxDim',
   'mode', 'out', 'ringSize', 'since', 'spanMs', 'stableMs', 'timeoutMs',
+  'last', 'runs', 'suite', 'keepLast', 'reason',
 ]);
 
 function parseArgs(argv) {
@@ -154,6 +181,40 @@ async function mapText(device, options, identity) {
   }
 }
 
+/**
+ * Wait for Enter, on a terminal or on a pipe.
+ *
+ * `readline/promises` looked like the obvious choice and threw "readline was
+ * closed" the first time it was asked a question after piped input ran out —
+ * which is how a smoke test of `baseline record` would have handed a stack
+ * trace to the person recording. Buffered lines are queued, and a closed
+ * stream is reported as what it is rather than thrown from inside a library.
+ */
+async function lineReader() {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, terminal: Boolean(process.stdin.isTTY) });
+  const queue = [];
+  const waiters = [];
+  let closed = false;
+  rl.on('line', (line) => (waiters.length ? waiters.shift()({ line }) : queue.push(line)));
+  rl.on('close', () => {
+    closed = true;
+    while (waiters.length) waiters.shift()({ closed: true });
+  });
+  return {
+    async enter(prompt) {
+      process.stdout.write(prompt);
+      const got = queue.length ? { line: queue.shift() } : closed ? { closed: true } : await new Promise((r) => waiters.push(r));
+      if (got.closed) {
+        throw new Error('stdin closed before the run ended — baseline record needs an interactive terminal');
+      }
+      process.stdout.write('\n');
+      return got.line;
+    },
+    close: () => rl.close(),
+  };
+}
+
 /** A step result, the same shape in every command that runs steps. */
 const stepLine = (r) => {
   const settle = r.settled ? (r.settled.ok ? ` (settled ${r.settled.waitedMs}ms)` : ' (never settled)') : '';
@@ -251,6 +312,29 @@ async function main() {
       return;
     }
 
+    // Rebuild the daemon's HID session, and nothing else.
+    //
+    // The narrow remedy for the narrow fault. Restarting the daemon also cures
+    // a stale session and throws away the frame ring and every warm cache to do
+    // it, which is the difference between a fix and a power cycle.
+    case 'input': {
+      const what = positional[0];
+      if (what !== 'reset') throw new Error('usage: simframe input reset [--device <udid>]');
+      const dev = await resolveDevice(device);
+      const before = await input.sessionHealth(dev.udid);
+      const reset = await input.resetSession(dev.udid);
+      if (!reset) {
+        // Said plainly rather than as a success: there is no daemon holding a
+        // session to rebuild, so nothing was wrong and nothing was done.
+        console.log(`no simframed session to rebuild for ${dev.name} — the daemon is not running, or this device is not driven by it`);
+        process.exitCode = 1;
+        return;
+      }
+      console.log(`rebuilt the HID session for ${dev.name}`
+        + (before.stale ? `\n  it was stale: ${before.reason}` : '\n  it did not report stale; rebuilt anyway, as asked'));
+      return;
+    }
+
     case 'status': {
       const udids = device
         ? [(await resolveDevice(device)).udid]
@@ -305,13 +389,23 @@ async function main() {
     }
 
     case 'state': {
-      const res = await api.getState(device, { since: flags.since, options });
+      const res = await api.getState(device, { since: flags.since, options, inputHealth: true });
       if (flags.json) {
         console.log(JSON.stringify({ ...res.state, history: undefined, ageMs: res.ageMs, since: res.since, live: res.live }, null, 2));
       } else {
         const s = res.state;
         const out = [];
         if (!res.live.ok) out.push(`WARNING: ${res.live.note}`);
+        // A cause, rather than five silent no-ops. Every tap on a stale
+        // session is dispatched successfully and moves nothing.
+        if (res.input?.stale) out.push(`input: stale — ${res.input.reason}`);
+        if (res.timing?.samples) {
+          out.push(
+            `timing: this screen usually arrives in ${res.timing.edge_p50}ms (p95 ${res.timing.edge_p95}ms, `
+            + `${res.timing.samples} samples); ${res.timing.elapsed_ms}ms since the last change`
+            + (res.timing.slower_than_usual ? ` — ${res.timing.note}` : ''),
+          );
+        }
         out.push(`${res.device.name}  frame #${s.seq}  age ${res.ageMs}ms  ${s.width}x${s.height}`);
         out.push(`hash ${s.hash}  stable ${s.stableForMs}ms`);
         if (res.since?.kind === 'history') {
@@ -724,6 +818,217 @@ async function main() {
       return;
     }
 
+    case 'baseline': {
+      const [sub, name] = positional;
+      const suite = baseline.loadSuite(flags.suite ?? baseline.SUITE_FILE);
+
+      if (sub === 'list' || sub == null) {
+        const dev = await resolveDevice(flags.device);
+        const committed = baseline.readBaselines();
+        const rows = suite.map((f) => {
+          const runs = baseline.readRuns(dev.udid, f.name);
+          return {
+            flow: f.name,
+            recorded_runs: runs.length,
+            committed: Boolean(committed[f.name]),
+            human_median_ms: committed[f.name]?.wall_time_ms?.p50 ?? null,
+            min_steps: f.minSteps ?? null,
+          };
+        });
+        emit(flags, rows, rows.map((r) =>
+          `${r.flow.padEnd(24)} ${String(r.recorded_runs).padStart(2)} run${r.recorded_runs === 1 ? ' ' : 's'}` +
+          `  ${r.committed ? `committed, human p50 ${r.human_median_ms}ms` : 'not committed'}`));
+        return;
+      }
+
+      if (sub === 'exclude') {
+        if (!name) throw new Error('usage: simframe baseline exclude <flow> --keep-last=<n> [--reason="..."]');
+        const dev = await resolveDevice(flags.device);
+        baseline.flowFrom(suite, name);
+        const keepLast = num(flags.keepLast, NaN);
+        if (!Number.isFinite(keepLast)) throw new Error('pass --keep-last=<n>: how many of the most recent runs to keep');
+        const res = baseline.excludeRuns(dev.udid, name, { keepLast, reason: flags.reason ? String(flags.reason) : undefined });
+        emit(flags, res, `${name}: ${res.excluded} of ${res.total} run(s) marked excluded — the runs stay in the log, carrying why`);
+        return;
+      }
+
+      if (sub === 'summarize') {
+        if (!name) throw new Error('usage: simframe baseline summarize <flow>');
+        const dev = await resolveDevice(flags.device);
+        const flow = baseline.flowFrom(suite, name);
+        const runs = baseline.readRuns(dev.udid, name);
+        const res = baseline.summarizeRuns(name, runs, { minSteps: flow.minSteps ?? null, device: dev.udid });
+        if (!res.ok) {
+          emit(flags, res, `${runs.length} recorded run${runs.length === 1 ? '' : 's'} for "${name}" — ` +
+            `${baseline.MIN_RUNS} is the floor and ${baseline.WANT_RUNS} is the recommendation. ` +
+            `Record more: simframe baseline record ${name} --device=${dev.udid}`);
+          process.exitCode = 1;
+          return;
+        }
+        const file = flags.out ? baseline.writeSummary(res.summary, { dir: path.dirname(flags.out) }) : baseline.writeSummary(res.summary);
+        const w = res.summary.wall_time_ms;
+        emit(flags, { ...res.summary, file }, [
+          `${name}: ${res.summary.runs} runs`,
+          `  wall time  p50 ${w.p50}ms   IQR ${w.p25}–${w.p75}ms   range ${w.min}–${w.max}ms`,
+          `  steps      p50 ${res.summary.steps_observed.p50} (from screen transitions; min_steps ${res.summary.min_steps ?? '?'} from the flow)`,
+          res.summary.runs_with_incomplete_history
+            ? `  WARNING ${res.summary.runs_with_incomplete_history} run(s) outran the 90s frame history; their step counts are undercounts`
+            : null,
+          `  wrote ${file}`,
+        ]);
+        return;
+      }
+
+      if (sub === 'record') {
+        if (!name) throw new Error('usage: simframe baseline record <flow>');
+        const flow = baseline.flowFrom(suite, name);
+        const dev = await resolveDevice(flags.device);
+        const wanted = Math.max(1, num(flags.runs, 1));
+        const rl = await lineReader();
+        const done = [];
+        try {
+          console.log(`${name} on ${dev.name} (${dev.udid})`);
+          console.log(`${flow.note ?? ''}\n`);
+          console.log('Do this, at your natural pace:');
+          for (const [i, line] of (flow.human ?? []).entries()) console.log(`  ${i + 1}. ${line}`);
+          console.log(`\nThe shortest route is ${flow.minSteps} steps. Practise once or twice first —`);
+          console.log('a baseline should measure a tester who knows the flow, not one discovering it.\n');
+          for (let run = 1; run <= wanted; run += 1) {
+            const reset = await baseline.resetFor(dev.udid, flow);
+            if (reset.failures.length) console.log(`  (reset: ${reset.failures.join('; ')})`);
+            await rl.enter(`run ${run}/${wanted} — device is on the home screen. Press Enter, then do the flow: `);
+            const res = await baseline.recordHumanRun(dev.udid, name, {
+              suite,
+              options,
+              waitForStop: () => rl.enter(`  timing... press Enter the moment you are on "${flow.endsOn ?? 'the last screen'}": `),
+            });
+            done.push(res.run);
+            const r = res.run;
+            console.log(`  ${r.wall_time_ms}ms, ${r.steps_observed} screen transitions` +
+              (r.history_complete === false ? ' — WARNING: longer than the frame history, steps undercounted' : ''));
+          }
+        } finally {
+          rl.close();
+        }
+        const total = baseline.readRuns(dev.udid, name).length;
+        emit(flags, { flow: name, recorded: done, runs_on_file: total }, [
+          '',
+          `${done.length} run${done.length === 1 ? '' : 's'} recorded — ${total} on file for "${name}"`,
+          total < baseline.WANT_RUNS
+            ? `${baseline.WANT_RUNS - total} more would meet the recommendation; ${Math.max(0, baseline.MIN_RUNS - total)} more is the floor`
+            : `enough to summarize: simframe baseline summarize ${name} --device=${dev.udid}`,
+        ]);
+        return;
+      }
+
+      throw new Error('usage: simframe baseline <record|summarize|list> [flow]');
+    }
+
+    case 'hpi': {
+      const dev = await resolveDevice(flags.device);
+      const suite = baseline.loadSuite(flags.suite ?? baseline.SUITE_FILE);
+      const names = new Set(suite.map((f) => f.name));
+      const all = metrics.readFlows(dev.udid);
+      // Named runs only, and only flows this suite defines. An ad-hoc `sim_do`
+      // is timed and logged, but it has no human counterpart and averaging it
+      // into a parity index would be inventing a comparison.
+      let runs = all.filter((f) => f.flow_name && names.has(f.flow_name) && (!flags.flow || f.flow_name === flags.flow));
+      // `--last=n` keeps the n most recent runs of each flow. The log is
+      // append-only on purpose — it is the trend — but a local log carries
+      // runs from a wedged device and from a bug since fixed, and averaging
+      // those into today's number describes neither day. CI computes its
+      // number from one process's own runs and never needs this.
+      if (flags.last) {
+        const keep = num(flags.last);
+        const perFlow = new Map();
+        for (const r of runs) perFlow.set(r.flow_name, [...(perFlow.get(r.flow_name) ?? []), r]);
+        runs = [...perFlow.values()].flatMap((rs) => rs.slice(-keep));
+      }
+      const report = metrics.hpi({ flows: runs, baselines: baseline.readBaselines() });
+      if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify(report, null, 2)}\n`);
+      if (!runs.length) {
+        emit(flags, report, [
+          `no runs of any suite flow on this device yet (${all.length} unnamed run${all.length === 1 ? '' : 's'} in the log)`,
+          'run the agent side: node scripts/bench-hpi.mjs --device=' + dev.udid,
+        ]);
+        return;
+      }
+      emit(flags, report, [
+        flags.last ? `the last ${num(flags.last)} run(s) of each flow, of ${all.filter((f) => f.flow_name).length} named runs in the log` : null,
+        'flow                      runs  agent p50   human p50   HPI_time  step_ratio  turns  esc',
+        ...report.flows.map((f) =>
+          `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
+          `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
+          `${(f.hpi_time ?? '—').toString().padStart(8)}  ${(f.step_ratio ?? '—').toString().padStart(10)}  ` +
+          `${(f.model_turns ?? '—').toString().padStart(5)}  ${String(f.escalations).padStart(3)}`),
+        '',
+        `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} runs, ` +
+          `${report.overall.runs - runs.filter((r) => r.completed && !r.wrong_action_taken).length} not clean)`,
+        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}`,
+        `step_ratio ${report.overall.step_ratio ?? '—'} (target ≤1.5), model turns per flow ${report.overall.model_turns_median ?? '—'}`,
+        flags.out ? `wrote ${flags.out}` : null,
+      ]);
+      return;
+    }
+
+    case 'escalations': {
+      const dev = await resolveDevice(flags.device);
+      const records = metrics.readEscalations(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      const b = metrics.breakdown(records, {
+        session: flags.session === true ? metrics.sessionId() : (flags.session ? String(flags.session) : null),
+        flow: flags.flow ? String(flags.flow) : null,
+      });
+      if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify(b, null, 2)}\n`);
+      emit(flags, b, [
+        `${b.total} escalation${b.total === 1 ? '' : 's'} on ${dev.name}`,
+        ...metrics.REASONS
+          .filter((r) => b.by_reason[r])
+          .sort((a, c) => b.by_reason[c] - b.by_reason[a])
+          .map((r) => `  ${r.padEnd(20)} ${String(b.by_reason[r]).padStart(4)}   `
+            + (metrics.BUILT_FACULTIES.has(metrics.FACULTY[r])
+              ? `not removed by: ${metrics.FACULTY[r]} [built]`
+              : `would be removed by: ${metrics.FACULTY[r]}`)),
+        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
+        // 1.0 while no faculty exists, so the breakdown above is the number
+        // that decides the next phase.
+        b.total && b.avoidable_escalation_rate === 1
+          ? (metrics.REASONS.some((r) => b.by_reason[r] && metrics.BUILT_FACULTIES.has(metrics.FACULTY[r]))
+            ? '  the rate is 1.0 because nothing resolves locally yet. A reason marked [built] is not a queue waiting on a phase — it is evidence the phase that shipped is not sufficient.'
+            : '  every reason maps to a faculty that is not built yet, so this rate is 1.0 by construction. The per-reason counts are the steering wheel.')
+          : null,
+        b.total ? `model turns spent on escalations: ${b.model_turns_spent}` : null,
+        // The log is per-device and shared. Said before the counts are used,
+        // not after: two agents on one booted simulator write one interleaved
+        // file, and CLAUDE.md makes these counts the thing that picks the next
+        // faculty. A pooled breakdown errs toward whichever session made more
+        // mistakes, which is a different question.
+        b.pooled
+          ? 'WARNING these counts may pool more than one agent\'s work: '
+            + [
+              b.session_count > 1 ? `${b.session_count} sessions` : null,
+              b.unattributed ? `${b.unattributed} record(s) written before sessions were logged` : null,
+            ].filter(Boolean).join(', ')
+            + '. Narrow with --session (this process), --session=<id>, or --flow=<name>.'
+          : null,
+        b.session_count > 1 ? 'sessions:' : null,
+        ...(b.session_count > 1
+          ? b.sessions.map((x) => `  ${x.session_id.padEnd(22)} ${String(x.count).padStart(4)}  ${x.client}`)
+          : []),
+        Object.keys(b.by_flow).length > 1 ? 'flows:' : null,
+        ...(Object.keys(b.by_flow).length > 1
+          ? Object.entries(b.by_flow).slice(0, 10).map(([n, c]) => `  ${n.padEnd(28)} ${String(c).padStart(4)}`)
+          : []),
+        b.top_screens.length ? 'top screens:' : null,
+        ...b.top_screens.map((s) => `  ${s.fingerprint.slice(0, 16).padEnd(18)} ${s.count}`),
+        metrics.writeError() ? `WARNING a log write failed: ${metrics.writeError()}` : null,
+      ]);
+      return;
+    }
+
     case 'devices': {
       const all = await listDevices();
       const shown = flags.all ? all : all.filter((d) => d.state === 'Booted');
@@ -772,6 +1077,52 @@ async function main() {
  * removed, and a fresh machine without it has not degraded from anything.
  * Strict fails on warn and fail, never on optional.
  */
+/**
+ * Is the device's display black, or is it only simframe that cannot read it?
+ *
+ * Two very different faults with one symptom, and telling them apart by hand
+ * took an hour: `simctl io screenshot` on a wedged device wrote a valid PNG
+ * whose 3.16 million pixels were all black, in 16.2 s. So the display pipeline
+ * had failed and simframe's read was an accurate report of it.
+ *
+ * Slow on purpose-built-in: this runs once, only when capture has already
+ * declared itself stalled, and 16 s of certainty beats an hour of guessing.
+ */
+async function blackScreenProbe(udid) {
+  const file = path.join(os.tmpdir(), `simframe-probe-${Date.now()}.png`);
+  const startedAt = Date.now();
+  try {
+    await screenshot(udid, file);
+    const png = decodePng(fs.readFileSync(file));
+    let lit = 0;
+    for (let i = 0; i < png.data.length; i += 4) {
+      if (png.data[i] > 12 || png.data[i + 1] > 12 || png.data[i + 2] > 12) lit += 1;
+    }
+    const ms = Date.now() - startedAt;
+    const pixels = png.data.length / 4;
+    if (lit === 0) {
+      return {
+        value: 'black',
+        detail: `the device's display is rendering black — every one of ${pixels.toLocaleString()} pixels, `
+          + `confirmed through Apple's own screenshot path in ${ms}ms. This is the simulator, not simframe: `
+          + 'it often recovers on its own, and restarting the device also cures it. Re-resolving the '
+          + 'display port and rebinding the device have both been tried — 223 and 6 times — and neither '
+          + 'makes any difference, because there is nothing wrong with the handle.',
+      };
+    }
+    return {
+      value: 'readable-by-simctl',
+      detail: `simctl can see ${lit.toLocaleString()} lit pixels of ${pixels.toLocaleString()} in ${ms}ms `
+        + 'while the daemon cannot read the surface at all. That is a simframe bug, not a wedged simulator — '
+        + 'worth reporting with this line.',
+    };
+  } catch (err) {
+    return { value: 'unreadable', detail: `even simctl could not screenshot this device: ${err.message}` };
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
 async function doctor({ json = false, strict = false, device } = {}) {
   const checks = [];
   // `level` is 'ok' | 'warn' | 'fail'. A warn means it works but not the way it
@@ -905,6 +1256,49 @@ async function doctor({ json = false, strict = false, device } = {}) {
           driver.available ? `${driver.name}: ${driver.version}` : driver.reason,
           { key: 'input.driver', value: driver.available ? driver.name : null });
       }
+      // When capture is wedged, say whose fault it is.
+      //
+      // Established the hard way: on a wedged device, Apple's own
+      // `simctl io screenshot` still succeeds — and returns an image with zero
+      // non-black pixels, in 16 seconds instead of one. The simulator's
+      // display pipeline is rendering black; simframe's IOSurface read is not
+      // the thing that broke. Re-resolving the port does not help, and neither
+      // does rebinding the device: both were tried, the second six times.
+      //
+      // That distinction is the whole value of this check. "simframe cannot
+      // read the display" invites someone to debug simframe; "the device's
+      // display is black and Apple's screenshot agrees" tells them to restart
+      // the device. The probe costs one screenshot and only runs when capture
+      // has already given up.
+      const wedged = store.captureHealth(d.udid)?.stalled;
+      if (wedged) {
+        const probe = await blackScreenProbe(d.udid);
+        add(`display (${d.name})`, 'fail', probe.detail, { key: 'display.probe', value: probe.value });
+      }
+
+      // Reported next to the driver it is about. A driver that is present and
+      // working is still useless if it holds a session for a device session
+      // that no longer exists, and that state was invisible: taps were
+      // dispatched successfully and moved nothing, five runs in a row.
+      const session = await input.sessionHealth(d.udid);
+      if (session.stale) {
+        // The remedy used to read "the next action rebuilds it automatically;
+        // simframe stop && simframe start does it now", and both halves were
+        // wrong. The first was false wherever it mattered, because the rebuild
+        // check was gated once per process and the MCP server is one process
+        // for a whole session. The second names a command that fails twice:
+        // `stop` needs `--device` when two simulators are booted, and then
+        // refuses because a client holds the daemon, so the sequence that
+        // actually works is `stop --device <udid> --force && start --device
+        // <udid>` — a daemon restart, to fix a session, when rebuilding the
+        // session is a thing the daemon can already do on request. It just had
+        // no way in from outside. It does now.
+        add(`input session (${d.name})`, 'warn', `stale — ${session.reason}. The next action rebuilds it; simframe input reset --device ${d.udid} does it now`,
+          { key: 'input.session', value: 'stale' });
+      } else if (caps.input.supported) {
+        add(`input session (${d.name})`, 'ok', session.reason ?? 'current with this device session',
+          { key: 'input.session', value: 'current' });
+      }
       add(`text recognition (${d.name})`, 'ok',
         daemon ? 'simframed (in-process, off the framebuffer)' : 'sips + helper binary');
       if (!caps.ax.supported) {
@@ -923,8 +1317,20 @@ async function doctor({ json = false, strict = false, device } = {}) {
     if (probed.length) {
       const t0 = Date.now();
       const res = await api.getFrame(probed[0].udid);
-      add('capture', 'ok',
-        `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`,
+      // The wedge's whole signature is that everything here reports success.
+      // A black frame is 32 integer comparisons on a signature already
+      // computed, and it is what separates "captured a frame" from "captured
+      // a frame of a display that has stopped rendering".
+      const dark = analyze.isBlackFrame(
+        (res.state.history ?? []).find((h) => h.seq === res.state.seq)?.sig ?? null,
+      );
+      add('capture', dark ? 'warn' : 'ok',
+        `frame #${res.state.seq} ${res.width}x${res.height} in ${Date.now() - t0}ms (age ${res.ageMs}ms)`
+        + (dark
+          ? ' — and every pixel of it is black. If the device is not showing a black screen on purpose,'
+            + ' this is the display pipeline having stopped rendering; it usually recovers on its own,'
+            + ` and ${'xcrun simctl shutdown'} / boot is the cure that always works.`
+          : ''),
         { key: 'capture.frames', value: res.state.seq });
       // A wedged device produces the same nothing as a quiet one, so doctor has
       // to ask the capture loop rather than look at the frames. `fail`, not

package/src/daemon.js

@@ -92,6 +92,15 @@ export async function runDaemon(device, options = {}) {
   let prevSignature = null;
   /** Recent frames, so a caller can diff against whatever it last saw rather
    *  than only against the frame that happened to precede this one. */
+  // A new capture session inherits no stall.
+  //
+  // capture-health.json is cleared when a stalled loop captures a frame again,
+  // and a loop that dies while stalled never gets to. So a fresh daemon ran
+  // healthily while `doctor` reported "stalled for 221s, 60 re-attaches" from
+  // its predecessor, and the display probe — correctly, on that input — called
+  // it a simframe bug. It was: this one.
+  store.writeCaptureHealth(udid, null);
+
   let history = [];
   /** seq + timestamp for every frame still on disk, so retention can be thinned by age. */
   let ringIndex = [];

package/src/fingerprint.js

@@ -24,8 +24,14 @@ import * as regions from './regions.js';
  *     browser's address bar put "== example.com" into a screen's identity, so
  *     a different page read as a different screen, and OCR's ":" and "+" read
  *     off icons were identities of their own.
+ * 4 — not a token-rule change at all, and bumped anyway: the screen map now
+ *     merges an OCR reading that sits inside a labelled ax element into that
+ *     element, so the target list these rules run over is shorter on every
+ *     list screen. Same rules, different input, therefore different hashes —
+ *     and a stored hash that can never match again is the quietest kind of
+ *     wrong, which is what this counter exists to prevent.
  */
-export const TOKEN_RULES_VERSION = 3;
+export const TOKEN_RULES_VERSION = 4;
 
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;