simframe 0.7.2 → 0.9.0

package/src/cli.js

@@ -1,12 +1,16 @@
 #!/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 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';
 
@@ -36,6 +40,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 +55,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 +120,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 +179,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)') : '';
@@ -243,6 +302,11 @@ async function main() {
         `stopped ${stopped} daemon${stopped === 1 ? '' : 's'}` +
           (inUse ? `; left ${inUse} in use by another client (pass --force to stop anyway)` : ''),
       );
+      // Asked to stop one device, refused, and exited 0 — which is a success
+      // code for work not done, and a script checking `$?` could not tell the
+      // difference. `--all` is informational by nature, so it keeps exiting 0
+      // when it skips a device somebody else holds.
+      if (!flags.all && inUse && !stopped) process.exitCode = 1;
       return;
     }
 
@@ -300,13 +364,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') {
@@ -719,6 +793,188 @@ 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);
+      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)}   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
+          ? '  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,
+        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');
@@ -767,6 +1023,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
@@ -900,6 +1202,38 @@ 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) {
+        add(`input session (${d.name})`, 'warn', `stale — ${session.reason}. The next action rebuilds it automatically; simframe stop && simframe start 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) {

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;

package/src/graph.js

@@ -9,11 +9,75 @@ import path from 'node:path';
 import { hashDistance } from './analyze.js';
 import { informative } from './refs.js';
 import * as fingerprint from './fingerprint.js';
+import * as metrics from './metrics.js';
 import * as matching from './matching.js';
 import * as store from './store.js';
 
 const GRAPH_VERSION = 3;
 
+/**
+ * How many observed settle durations an edge remembers. Research §7.
+ *
+ * Fifty is a window, not a history: an app that got faster after an update
+ * should stop being waited for at its old speed, and a mean over everything
+ * ever observed never forgets.
+ */
+export const TIMING_WINDOW = 50;
+/** Below this many samples an edge has no distribution worth trusting. */
+export const COLD_SAMPLES = 5;
+/**
+ * What a cold edge waits: exactly what every step waited before Phase 11.
+ *
+ * Deliberately unchanged, so the first traversal of an edge behaves as it
+ * always did and only a *measured* edge gets a tighter bound. A conservative
+ * default that is also the historical default cannot make anything worse.
+ */
+export const COLD_TIMEOUT_MS = 8000;
+/**
+ * The hard cap on waiting, from research §7: Nielsen's attention limit. Past
+ * ten seconds a person has stopped believing the screen is coming, and so
+ * should the agent — it escalates instead.
+ */
+export const HARD_CAP_MS = 10_000;
+
+/**
+ * How long to wait for a transition that has been measured.
+ *
+ * p95 plus a margin, where the margin is the larger of 150 ms and a fifth of
+ * p95. The floor matters for fast edges: a tab switch with a p95 of 90 ms
+ * would otherwise get a 108 ms budget, and one slow frame would call a
+ * perfectly ordinary transition a timeout.
+ */
+export function adaptiveTimeout({ p95, samples } = {}) {
+  if (!Number.isFinite(p95) || !Number.isFinite(samples) || samples < COLD_SAMPLES) {
+    return { timeoutMs: COLD_TIMEOUT_MS, cold: true, reason: `fewer than ${COLD_SAMPLES} samples` };
+  }
+  const margin = Math.max(150, Math.round(p95 * 0.2));
+  return { timeoutMs: Math.min(HARD_CAP_MS, p95 + margin), cold: false, reason: null, margin };
+}
+
+/**
+ * Is this transition taking longer than this edge usually does?
+ *
+ * Two different answers hide behind a slow transition, and §7 asks for both:
+ * a screen that is *working* (a spinner, a load) should be waited for up to
+ * the hard cap, while a screen that is doing nothing visible has already
+ * given its answer. The classifier's `loading` kind is what separates them.
+ */
+export function slowerThanUsual({ elapsedMs, p95, settled, kind } = {}) {
+  if (settled || !Number.isFinite(elapsedMs) || !Number.isFinite(p95)) return { slower: false };
+  if (elapsedMs <= p95) return { slower: false };
+  const working = kind === 'loading';
+  return {
+    slower: true,
+    working,
+    keepWaiting: working && elapsedMs < HARD_CAP_MS,
+    note: working
+      ? `slower than usual (${elapsedMs}ms against a p95 of ${p95}ms) and still loading`
+      : `slower than usual (${elapsedMs}ms against a p95 of ${p95}ms) with nothing visibly happening`,
+  };
+}
+
 /**
  * Which fingerprint produced the hashes in these files.
  *
@@ -276,7 +340,100 @@ export function findScreen(udid, query) {
 }
 
 /** Remember that doing `action` on `from` led to `to`. */
-export function record(udid, { from, action, to, kind }) {
+/**
+ * Add one observed settle duration to an edge's rolling window.
+ *
+ * Kept on the edge rather than in a separate store because it is a property of
+ * this transition on this screen — the same tap costs 90 ms on a tab bar and
+ * 2.4 s on a screen that fetches — and because the graph is already persisted,
+ * versioned and pruned.
+ */
+function noteSettle(edge, settleMs, quietGapMs) {
+  if (Number.isFinite(settleMs) && settleMs >= 0) {
+    edge.settles = [...(edge.settles ?? []), Math.round(settleMs)].slice(-TIMING_WINDOW);
+  }
+  // Recorded even when zero: "this transition never paused" is exactly the
+  // observation that lets the next one stop waiting 500ms to find out.
+  if (Number.isFinite(quietGapMs) && quietGapMs >= 0) {
+    edge.quietGaps = [...(edge.quietGaps ?? []), Math.round(quietGapMs)].slice(-TIMING_WINDOW);
+  }
+}
+
+/**
+ * How long a screen must hold still on this edge before it is finished.
+ *
+ * Derived from the longest pause ever seen *inside* this transition, plus a
+ * margin, and never longer than the caller's own default — this can only make
+ * a wait shorter, never longer, which is what keeps a learned number from
+ * becoming a new way to hang.
+ *
+ * The floor is 150 ms because a settle also needs at least one fresh frame to
+ * judge, and the capture loop's own idle interval is the limit on how fast an
+ * answer can arrive.
+ */
+export const STILLNESS_FLOOR_MS = 150;
+
+export function stillnessFor({ gapSamples, gapP95 } = {}, fallbackMs) {
+  if (!Number.isFinite(gapP95) || !Number.isFinite(gapSamples) || gapSamples < COLD_SAMPLES) {
+    return { stillnessMs: fallbackMs, cold: true };
+  }
+  const margin = Math.max(100, Math.round(gapP95 * 0.5));
+  return {
+    stillnessMs: Math.max(STILLNESS_FLOOR_MS, Math.min(fallbackMs, gapP95 + margin)),
+    cold: false,
+  };
+}
+
+/** What this edge's observed settle durations say, or that it has none. */
+export function timingOf(edge) {
+  const samples = edge?.settles ?? [];
+  const gaps = edge?.quietGaps ?? [];
+  return {
+    samples: samples.length,
+    p50: metrics.percentile(samples, 50),
+    p95: metrics.percentile(samples, 95),
+    gapSamples: gaps.length,
+    gapP95: metrics.percentile(gaps, 95),
+  };
+}
+
+/**
+ * How long to wait for `step` on `screen`, from what it has cost before.
+ *
+ * Returns the cold default when this screen or this action has not been
+ * measured, and says which — a timeout nobody can explain is how a fixed sleep
+ * gets reintroduced as a constant with a comment.
+ */
+export function timingFor(udid, screen, step) {
+  const node = screen?.hash ? nearestScreen(udid, screen)?.node : null;
+  const edge = node?.edges?.find((e) => e.action === actionSignature(step));
+  const stats = timingOf(edge);
+  return { ...stats, ...adaptiveTimeout(stats), known: Boolean(edge) };
+}
+
+/**
+ * What getting *to* this screen has cost before.
+ *
+ * `sim_state` is asked "what is on screen and is it done moving", with no
+ * action in hand, so there is no outgoing edge to consult. The useful answer
+ * is the inbound one: the edge most recently traversed into this screen is how
+ * we got here, and its distribution is what "slower than usual" means right
+ * now. Most recently seen rather than most travelled — a screen reachable two
+ * ways is being timed against the way it was just reached.
+ */
+export function timingInto(udid, hash) {
+  if (!hash) return null;
+  let best = null;
+  for (const node of allNodes(udid)) {
+    for (const edge of node.edges ?? []) {
+      if (edge.to !== hash) continue;
+      if (!best || (edge.lastSeen ?? 0) > (best.lastSeen ?? 0)) best = edge;
+    }
+  }
+  return best ? { ...timingOf(best), action: best.action, kind: best.kind ?? null } : null;
+}
+
+export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
   const fromKey = typeof from === 'string' ? { hash: from } : from;
   const toHash = typeof to === 'string' ? to : to?.hash;
   if (!fromKey?.hash || !toHash) return null;
@@ -343,6 +500,7 @@ export function record(udid, { from, action, to, kind }) {
         save(udid, target);
         existing.count += 1;
         existing.lastSeen = Date.now();
+        noteSettle(existing, settleMs, quietGapMs);
         save(udid, node);
         return node;
       }
@@ -354,6 +512,7 @@ export function record(udid, { from, action, to, kind }) {
     existing.kind = kind ?? existing.kind;
     existing.count += 1;
     existing.lastSeen = Date.now();
+    noteSettle(existing, settleMs);
   } else {
     node.edges.push({
       action: signature,
@@ -364,6 +523,8 @@ export function record(udid, { from, action, to, kind }) {
       kind,
       count: 1,
       lastSeen: Date.now(),
+      settles: Number.isFinite(settleMs) && settleMs >= 0 ? [Math.round(settleMs)] : [],
+      quietGaps: Number.isFinite(quietGapMs) && quietGapMs >= 0 ? [Math.round(quietGapMs)] : [],
     });
   }
   save(udid, node);