simframe 0.9.0 → 0.10.0

package/src/actions.js

@@ -27,11 +27,22 @@ const MAX_PAUSE_MS = 5000;
  * falls out at `reaction` instead. That bounds the cost of the honest case
  * rather than the broken one.
  */
+/**
+ * The stillness window stays fixed, and that is a decision rather than an
+ * oversight. Learning a stillness window is the half of Phase 11 that was
+ * reverted for cause: a wait that ends early never observes the pauses that
+ * come later, so the estimator ratchets itself down and the graph learns
+ * transitions that never happened. See docs/BENCHMARKS.md, Phase 11.
+ */
 const FOCUS_STABLE_MS = 250;
 /**
- * Long enough for a slow capture loop to produce a frame or two. The screenshot
- * engine idles at 1.5 fps — 667 ms between frames — so anything under that is a
- * verdict reached before there was anything to look at.
+ * The cold defaults, unchanged, for a field this screen has not been measured
+ * focusing. `graph.focusPlan` takes over once it has been, and may only make
+ * the wait longer.
+ *
+ * 900 ms is long enough for a slow capture loop to produce a frame or two. The
+ * screenshot engine idles at 1.5 fps — 667 ms between frames — so anything
+ * under that is a verdict reached before there was anything to look at.
  */
 const FOCUS_REACTION_MS = 900;
 const FOCUS_TIMEOUT_MS = 3000;
@@ -140,7 +151,7 @@ export async function runScript(
   // than no instrumentation.
   const noteEscalation = (record) => {
     try {
-      escalations.push(metrics.recordEscalation(udid, { flowId, ...record }));
+      escalations.push(metrics.recordEscalation(udid, { flowId, flowName, ...record }));
     } catch {
       /* instrumentation must not be able to fail a flow it is only watching */
     }
@@ -171,10 +182,35 @@ export async function runScript(
   // moves nothing and is not a failure, so an unbounded retry would rebuild the
   // session and press again on every such step for no reason.
   let inputRecovered = false;
+  /**
+   * The previous step's transition, still to be measured.
+   *
+   * Its pause profile cannot be read while the step is running — that is the
+   * biased measurement that corrupted the graph — so it is read one step later,
+   * off a frame history whose end nothing about the wait decided. See
+   * `api.longestQuietGap`.
+   */
+  let pendingGap = null;
+  const measurePendingGap = async () => {
+    if (!pendingGap) return;
+    const { from, step: prevStep, actionAt } = pendingGap;
+    pendingGap = null;
+    try {
+      const history = (await api.getState(deviceQuery, { options })).state.history ?? [];
+      const trueGapMs = api.longestQuietGap(history, actionAt);
+      if (trueGapMs != null) graph.noteTrueGap(udid, from, prevStep, trueGapMs);
+    } catch {
+      /* a statistic nothing acts on must never be able to fail a flow */
+    }
+  };
 
   for (const [i, raw] of steps.entries()) {
     const step = normalizeStep(raw);
     const stepStart = Date.now();
+    // Before anything else, and before this step disturbs the screen: the
+    // previous transition is definitely over by now, so its true pause profile
+    // is readable.
+    await measurePendingGap();
     // The baseline for "did the screen react" must predate the action itself.
     const beforeState = (await api.getState(deviceQuery, { options })).state;
     const before = beforeState.hash;
@@ -190,11 +226,24 @@ export async function runScript(
     // What this action did last time it was taken here, if ever.
     const prediction = verify && beforeScreen?.hash ? graph.predict(udid, beforeScreen, step) : null;
     try {
-      let detail = await runStep(deviceQuery, udid, step, { screen, options, frames });
       // How long this transition has cost before, on this screen, for this
       // action. A cold edge gets the old fixed default and says so; a measured
       // one gets p95 plus a margin. Research §7.
+      //
+      // Read before the step, not after, because one of the waits it informs
+      // happens *inside* the step: a `type into` taps the field and waits for
+      // focus before it types, and that wait used to be three constants.
       const learned = verify && beforeScreen?.hash ? graph.timingFor(udid, beforeScreen, step) : null;
+      const focus = {
+        plan: graph.focusPlan(learned, {
+          reactionMs: FOCUS_REACTION_MS,
+          timeoutMs: FOCUS_TIMEOUT_MS,
+          stillnessMs: FOCUS_STABLE_MS,
+          keyboardUp: Boolean(beforeScreen?.keyboard),
+        }),
+        observedMs: null,
+      };
+      let detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
       // How long this screen must hold still before it counts as settled.
       //
       // 500 ms was a constant paid by every step of every flow, and it is the
@@ -257,6 +306,15 @@ export async function runScript(
           budgetMs,
           stillnessMs: stillness,
           quietGapMs: w.quietGapMs,
+          // The baseline had already finished moving when the wait began, so it
+          // was re-taken from the live screen. Surfaced because it means the
+          // step before this one had not finished when this one started.
+          staleBaseline: Boolean(w.staleBaseline),
+          // Something moved in one region only — a switch, a radio dot, a
+          // segment highlight. Worth saying, because it is the difference
+          // between "the action did nothing" and "the action did something the
+          // whole-screen mean cannot see".
+          smallChange: Boolean(w.smallChange),
           timing: learned
             ? {
               p50: learned.p50,
@@ -343,7 +401,23 @@ export async function runScript(
         // for. Requiring both meant a screen that settled slowly recorded
         // nothing at all.
         endScreen = afterScreen;
-        if (afterScreen.confirmed && afterScreen.hash) {
+        // An action with no observed effect teaches the graph nothing, and
+        // recording it teaches something false.
+        //
+        // This is the second half of the same bug. A settle that returned on a
+        // stale baseline reported `ok` for a tap that moved nothing, and the
+        // recorder asked only whether the *reading* was confirmed — so
+        // `root -> root` went in as a verified edge and started being
+        // predicted. Re-baselining stops the settle lying; this stops the
+        // graph learning from a step that has no evidence behind it either way.
+        //
+        // It does cost a real case for now: a control that genuinely returns to
+        // the same screen — a toggle — is invisible to the change detector at
+        // eight times below its threshold, so it reads as no-visible-change and
+        // its edge is no longer recorded. That is the right trade while the
+        // detector cannot see it, and it comes back on its own once it can.
+        const noEvidence = Boolean(settled?.noVisibleChange);
+        if (afterScreen.confirmed && afterScreen.hash && !noEvidence) {
           // The observed cost of this transition, which is what makes the next
           // one adaptive. Only from a settle that was actually satisfied: a
           // timeout is not a measurement of how long the screen takes, it is a
@@ -356,13 +430,37 @@ export async function runScript(
             // 400ms and then timed out is exactly the case a 150ms stillness
             // window would have got wrong.
             quietGapMs: settled?.sawChange ? settled.quietGapMs : undefined,
+            // The focus wait's own distribution, kept apart from the step's.
+            // Only set when a field was tapped and visibly took focus.
+            focusMs: focus.observedMs ?? undefined,
           });
+          pendingGap = { from: beforeScreen, step, actionAt: stepStart };
+          carriedScreen = afterScreen;
+        } else if (afterScreen.confirmed && afterScreen.hash) {
+          // Where we are is still known; only what got us here is not worth
+          // remembering. Carrying it saves the next step a perception pass.
           carriedScreen = afterScreen;
         }
       }
 
       const wrongTurn = wrongTurnFrom(verification);
-      const note = settled?.noVisibleChange ? ' [no visible change]' : '';
+      // `[no visible change]` after a launch is ambiguous between two very
+      // different things, and a real session read it the wrong way twice:
+      // "the app was already in front, so nothing needed to move" and "the app
+      // did not come forward". Measured on this Xcode, `simctl launch` *does*
+      // front an already-running app, so the first reading is the likely one —
+      // but likely is not the same as said, and the step is the only place that
+      // can say it.
+      const launchNote = step.action === 'launch' && settled?.noVisibleChange
+        ? ' [the screen did not change, so this app was already in front — or it did not come forward]'
+        : '';
+      const note = launchNote
+        + (settled?.smallChange ? ' [a small change, in one region only]' : '')
+        + (settled?.noVisibleChange ? ' [no visible change]' : '')
+        + (settled?.staleBaseline ? ' [baseline had already settled; re-taken from the live screen]' : '')
+        + (settled?.blackFrames
+          ? ` [${settled.blackFrames} black frame(s) waited through${settled.blackMs ? `, still black after ${settled.blackMs}ms` : ''}]`
+          : '');
       results.push({
         index: i,
         action: step.action,
@@ -416,6 +514,10 @@ export async function runScript(
     }
   }
 
+  // The last step has no next step to measure it, and its transition is over by
+  // the time the loop exits.
+  await measurePendingGap();
+
   const wallMs = Date.now() - startedAt;
   try {
     metrics.recordFlow(udid, metrics.flowRecordFrom({
@@ -464,18 +566,31 @@ export async function runScript(
  */
 async function focusField(deviceQuery, udid, step, ctx) {
   const found = await api.locate(deviceQuery, step.into, { index: step.index, refresh: step.refresh });
+  // What this field has cost to focus before, on this screen. Cold, or with no
+  // verification running, that is exactly the three constants above; measured,
+  // it can only be longer. `graph.focusPlan` carries the reason it is either.
+  const plan = ctx.focus?.plan ?? {
+    reactionMs: FOCUS_REACTION_MS, timeoutMs: FOCUS_TIMEOUT_MS, cold: true, from: 'no timing in hand',
+  };
+  const tappedAt = Date.now();
   await input.tapPoint(udid, found.target.x, found.target.y);
   const focused = await api.waitFor(deviceQuery, {
     mode: 'settle',
     stableMs: FOCUS_STABLE_MS,
-    reactionMs: FOCUS_REACTION_MS,
-    timeoutMs: FOCUS_TIMEOUT_MS,
+    reactionMs: plan.reactionMs,
+    timeoutMs: plan.timeoutMs,
     options: ctx.options,
   });
+  // Only a wait that was satisfied is a measurement of how long focus takes. A
+  // reaction window that ran out measures how long we were prepared to watch a
+  // screen that did not move, and banking that would teach the edge the cost of
+  // its own impatience — the estimator mistake learned stillness made.
+  if (ctx.focus && focused.satisfied) ctx.focus.observedMs = Date.now() - tappedAt;
   return {
     found,
     where: `"${found.target.label}" at ${found.target.x},${found.target.y}`,
     quiet: focused.satisfied ? '' : ' [the field did not visibly take focus]',
+    waited: focused.satisfied && !plan.cold ? ` [focus in ${focused.waitedMs}ms, ${plan.from}]` : '',
   };
 }
 
@@ -507,7 +622,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
         await input.typeText(udid, step.text ?? step.value);
-        return `typed into ${field.where}${field.quiet}`;
+        return `typed into ${field.where}${field.quiet}${field.waited}`;
       }
       await input.typeText(udid, step.text ?? step.value);
       return 'typed text';
@@ -520,7 +635,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
       if (step.into) {
         const field = await focusField(deviceQuery, udid, step, ctx);
         await input.pasteText(udid, step.text ?? step.value);
-        return `pasted into ${field.where}${field.quiet}`;
+        return `pasted into ${field.where}${field.quiet}${field.waited}`;
       }
       await input.pasteText(udid, step.text ?? step.value);
       return 'pasted into the focused field';
@@ -600,6 +715,14 @@ async function runStep(deviceQuery, udid, step, ctx) {
           return `"${node.label ?? target}" appeared`;
         } catch (err) {
           lastError = err.message;
+          // Same rule as `waitFor`, and `matchElement` says it in its own
+          // words: a query that matched several elements has found them all
+          // already.
+          if (/matched \d+ elements/.test(err.message)) {
+            throw new Error(
+              `${err.message}\n  (not waiting: it is already on screen, and waiting cannot make it unique)`,
+            );
+          }
         }
         await sleep(250);
       }
@@ -652,6 +775,22 @@ async function runStep(deviceQuery, udid, step, ctx) {
           return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`;
         } catch (err) {
           lastError = err.message;
+          // Waiting cannot make a thing unique.
+          //
+          // Reported from a real session: a wait on an ambiguous string spent
+          // the full 30 s and then listed four matches, all four of which were
+          // on the very first frame. The disambiguation is good and it arrived
+          // twenty-nine seconds after everything it needed. `ambiguous` means
+          // the target is *present*, several times over — which is precisely
+          // the case where more time changes nothing.
+          //
+          // Distinguished by the tag at the throw site rather than by reading
+          // the message, because "not on this screen" tags the same reason.
+          if (metrics.escalationOf(err)?.ambiguous) {
+            throw new Error(
+              `${err.message}\n  (not waiting: it is already on screen, and waiting cannot make it unique)`,
+            );
+          }
         }
         if (Date.now() >= limit) break;
         await sleep(POLL_MS);

package/src/analyze.js

@@ -35,6 +35,42 @@ export function signatureDiff(a, b) {
   return sum / a.length / 255;
 }
 
+/**
+ * A change small enough that the whole-screen mean cannot see it.
+ *
+ * `changed` in both daemons is `signatureDiff > 0.004`, a mean over a 4x8 grid
+ * of gray means. Measured on this device, an iOS switch flipping:
+ *
+ *   mean diff        0.001348   — a third of the threshold, so: not a change
+ *   max cell delta   0.043137   — one cell of thirty-two, in row 1
+ *
+ * So the entire class of small binary controls — switches, radio dots,
+ * checkboxes, segment highlights — changes nothing as far as the daemon is
+ * concerned, and a step that flips one reports `no-visible-change`, which is a
+ * verdict that escalates.
+ *
+ * The threshold sits in a measured gap rather than being chosen. Eighty seconds
+ * of a *static* screen gave a largest per-cell delta of 0.003922, in row 0,
+ * which is the status-bar clock ticking over — the only thing moving. So the
+ * separation is 0.0039 against 0.0431, eleven times, and 0.012 is three times
+ * the noise and three and a half times under the signal. No row is excluded:
+ * the clock does not reach the threshold, which is a better reason to ignore it
+ * than a structural exclusion that would also blind the nav bar.
+ *
+ * What this deliberately does **not** do is feed stillness. `stableForMs` stays
+ * on the mean, because a blinking text caret is a small localised change and a
+ * screen with a cursor in it would otherwise never settle. The two signals are
+ * independent by design: this one answers "did the action do anything", and the
+ * mean answers "has the screen finished moving".
+ */
+export const CELL_CHANGE = 0.012;
+
+/** The largest single-region change between two signatures, 0-1. */
+export function maxCellDelta(a, b) {
+  const deltas = regionDeltas(a, b);
+  return deltas.length ? Math.max(...deltas) : 0;
+}
+
 /** Per-region change fractions, so callers can tell a toast from a screen push. */
 export function regionDeltas(a, b) {
   if (!a || !b || a.length !== b.length) return a ? a.map(() => 1) : [];
@@ -69,6 +105,40 @@ export function signatureToHex(sig) {
   return sig.map((v) => v.toString(16).padStart(2, '0')).join('');
 }
 
+/**
+ * Is this frame black — not dark, black?
+ *
+ * The capture wedge (docs/BENCHMARKS.md) leaves `simctl io screenshot`
+ * succeeding and returning 0 non-black pixels of 3,162,132, and simframe's own
+ * frames go the same way: the display pipeline stops rendering while
+ * everything about the capture path keeps reporting success. It self-recovers
+ * most times and a device restart cures the rest, so the useful thing is to
+ * notice early — before a settle spends its whole budget deciding a black
+ * screen is a calm one.
+ *
+ * The signature is already computed for every frame, so this costs 32 integer
+ * comparisons and no decode. A real screen does not come close: measured on
+ * this device's Settings root, the 32 bytes ran 191–245.
+ *
+ * The threshold is a level, not a fraction, and it is on the *maximum*: one
+ * cell with anything in it is enough to say the display is rendering. That
+ * matters because a dark-mode screen, a video, or a splash on black are all
+ * legitimately near-zero in most cells and this must not call them faults.
+ *
+ * And it says "the frames are black", never "the simulator is wedged". A
+ * screen can be black because the app drew black. What makes it a wedge is
+ * that it stays black while input is being delivered, and only the caller
+ * knows that.
+ */
+export const BLACK_LEVEL = 8;
+
+export function isBlackFrame(sig, { level = BLACK_LEVEL } = {}) {
+  const bytes = typeof sig === 'string' ? hexToSignature(sig) : sig;
+  if (!bytes?.length) return false;
+  for (const b of bytes) if (b > level) return false;
+  return true;
+}
+
 export function hexToSignature(hex) {
   const out = [];
   for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));

package/src/cli.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { runDaemon, DEFAULTS } from './daemon.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';
@@ -20,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
@@ -310,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]
@@ -951,23 +976,52 @@ async function main() {
     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);
+      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)}   would be removed by: ${metrics.FACULTY[r]}`),
+          .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
-          ? '  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.'
+          ? (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,
@@ -1228,7 +1282,18 @@ async function doctor({ json = false, strict = false, device } = {}) {
       // 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`,
+        // 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',
@@ -1252,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/graph.js

@@ -348,7 +348,7 @@ export function findScreen(udid, query) {
  * 2.4 s on a screen that fetches — and because the graph is already persisted,
  * versioned and pruned.
  */
-function noteSettle(edge, settleMs, quietGapMs) {
+function noteSettle(edge, settleMs, quietGapMs, focusMs) {
   if (Number.isFinite(settleMs) && settleMs >= 0) {
     edge.settles = [...(edge.settles ?? []), Math.round(settleMs)].slice(-TIMING_WINDOW);
   }
@@ -357,6 +357,39 @@ function noteSettle(edge, settleMs, quietGapMs) {
   if (Number.isFinite(quietGapMs) && quietGapMs >= 0) {
     edge.quietGaps = [...(edge.quietGaps ?? []), Math.round(quietGapMs)].slice(-TIMING_WINDOW);
   }
+  // How long the *field* took to take focus, which is a different duration from
+  // how long the step took: it is measured between the tap and the keyboard,
+  // inside a step whose settle is measured after the typing. One edge, two
+  // waits, so two distributions.
+  if (Number.isFinite(focusMs) && focusMs >= 0) {
+    edge.focuses = [...(edge.focuses ?? []), Math.round(focusMs)].slice(-TIMING_WINDOW);
+  }
+}
+
+/**
+ * Record the unbiased pause statistic for an edge already written.
+ *
+ * Separate from `record` because it arrives later on purpose. The biased
+ * `quietGaps` are gathered from inside the wait and are therefore bounded by
+ * when the wait chose to stop; `trueGaps` are read off the frame history once
+ * the transition is definitely over, which is one step later. So the edge has
+ * to be found again rather than passed along.
+ *
+ * Nothing reads `trueGaps` yet, and that is deliberate. Phase 11 built the
+ * learned stillness window on the biased statistic, it corrupted the graph
+ * inside an afternoon, and the lesson taken was not "use a better estimator" —
+ * it was that a number gets to *act* only after it has been watched for a while
+ * doing nothing. This is the watching.
+ */
+export function noteTrueGap(udid, screen, step, trueGapMs) {
+  if (!Number.isFinite(trueGapMs) || trueGapMs < 0) return null;
+  const node = screen?.hash ? nearestScreen(udid, screen)?.node : null;
+  if (!node) return null;
+  const edge = node.edges?.find((e) => e.action === actionSignature(step));
+  if (!edge) return null;
+  edge.trueGaps = [...(edge.trueGaps ?? []), Math.round(trueGapMs)].slice(-TIMING_WINDOW);
+  save(udid, node);
+  return edge;
 }
 
 /**
@@ -384,16 +417,76 @@ export function stillnessFor({ gapSamples, gapP95 } = {}, fallbackMs) {
   };
 }
 
+/**
+ * How long to wait for a tapped field to take focus.
+ *
+ * The three numbers this replaces were the last genuinely fixed waits on the
+ * action path: 250 ms of stillness, a 900 ms reaction window, a 3 s timeout.
+ * What makes them different from the step budget is the shape of the failure.
+ * A step budget that is too short reports `no-visible-change` and the flow can
+ * see it. A focus wait that is too short types into a field that does not have
+ * focus yet, `typeText` succeeds because input has no feedback channel, and the
+ * step reports that it typed — the worst shape a failure can take, and the bug
+ * this helper was written to fix in the first place.
+ *
+ * So this one is asymmetric on purpose: **a learned window may only lengthen
+ * the wait**, never shorten it. p95 of what this field has actually cost, when
+ * that is longer than 3 s, is a field that was being typed into too early and
+ * now is not. Where it is shorter, the measurement is discarded rather than
+ * banked as a saving — 5% of a distribution is one silent wrong type in twenty
+ * runs, and there is no amount of median wall time worth that.
+ *
+ * The one shortening is not a learned number at all, it is positive evidence:
+ * if the keyboard was already up before the tap, this tap moves a caret. There
+ * is no keyboard animation to wait for, so the reaction window collapses to the
+ * stillness window instead of paying 900 ms to watch a screen that was never
+ * going to move. `beforeScreen` already carries `keyboard`, so the evidence is
+ * free — it is the same perception pass the step was going to run anyway.
+ */
+export function focusPlan(stats, { reactionMs, timeoutMs, stillnessMs, keyboardUp } = {}) {
+  if (keyboardUp) {
+    return {
+      reactionMs: stillnessMs ?? reactionMs,
+      timeoutMs,
+      cold: false,
+      from: 'the keyboard was already up, so this tap moves a caret',
+    };
+  }
+  const { focusP50, focusP95, focusSamples } = stats ?? {};
+  if (!Number.isFinite(focusP95) || !Number.isFinite(focusSamples) || focusSamples < COLD_SAMPLES) {
+    return { reactionMs, timeoutMs, cold: true, from: `fewer than ${COLD_SAMPLES} focus samples` };
+  }
+  const margin = Math.max(150, Math.round(focusP95 * 0.2));
+  const learnedTimeout = Math.min(HARD_CAP_MS, focusP95 + margin);
+  const learnedReaction = Math.min(learnedTimeout, focusP50 + margin);
+  return {
+    // max, not min. See above: only ever longer.
+    reactionMs: Math.max(reactionMs, learnedReaction),
+    timeoutMs: Math.max(timeoutMs, learnedTimeout),
+    cold: false,
+    from: `p95 ${focusP95}ms over ${focusSamples} focus samples`,
+  };
+}
+
 /** 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 ?? [];
+  const focuses = edge?.focuses ?? [];
   return {
     samples: samples.length,
     p50: metrics.percentile(samples, 50),
     p95: metrics.percentile(samples, 95),
     gapSamples: gaps.length,
     gapP95: metrics.percentile(gaps, 95),
+    // The same statistic measured after the transition rather than during it.
+    // Reported side by side so the size of the bias is visible rather than
+    // argued about — see `index.longestQuietGap`.
+    trueGapSamples: (edge?.trueGaps ?? []).length,
+    trueGapP95: metrics.percentile(edge?.trueGaps ?? [], 95),
+    focusSamples: focuses.length,
+    focusP50: metrics.percentile(focuses, 50),
+    focusP95: metrics.percentile(focuses, 95),
   };
 }
 
@@ -433,7 +526,7 @@ export function timingInto(udid, hash) {
   return best ? { ...timingOf(best), action: best.action, kind: best.kind ?? null } : null;
 }
 
-export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
+export function record(udid, { from, action, to, kind, settleMs, quietGapMs, focusMs }) {
   const fromKey = typeof from === 'string' ? { hash: from } : from;
   const toHash = typeof to === 'string' ? to : to?.hash;
   if (!fromKey?.hash || !toHash) return null;
@@ -500,7 +593,7 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
         save(udid, target);
         existing.count += 1;
         existing.lastSeen = Date.now();
-        noteSettle(existing, settleMs, quietGapMs);
+        noteSettle(existing, settleMs, quietGapMs, focusMs);
         save(udid, node);
         return node;
       }
@@ -512,7 +605,13 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
     existing.kind = kind ?? existing.kind;
     existing.count += 1;
     existing.lastSeen = Date.now();
-    noteSettle(existing, settleMs);
+    // Every argument, and it is worth saying why this line once passed one.
+    // `quietGapMs` was dropped here — on the *main* path, the one nearly every
+    // recorded edge takes — so the pause statistic only ever accumulated on a
+    // brand-new edge and on the variant branch. The window that reads it looked
+    // permanently cold, which is a measurement quietly not being taken rather
+    // than a wrong number, and those are the ones nothing complains about.
+    noteSettle(existing, settleMs, quietGapMs, focusMs);
   } else {
     node.edges.push({
       action: signature,
@@ -525,6 +624,7 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
       lastSeen: Date.now(),
       settles: Number.isFinite(settleMs) && settleMs >= 0 ? [Math.round(settleMs)] : [],
       quietGaps: Number.isFinite(quietGapMs) && quietGapMs >= 0 ? [Math.round(quietGapMs)] : [],
+      focuses: Number.isFinite(focusMs) && focusMs >= 0 ? [Math.round(focusMs)] : [],
     });
   }
   save(udid, node);