simframe 0.12.2 → 0.13.0

package/scripts/eval-fingerprint.mjs

@@ -164,8 +164,21 @@ for (let round = 1; round <= rounds; round += 1) {
       // means the navigation did not happen.
       const s = fingerprint.similarity(previous.tokens, id.tokens ?? []);
       if (s >= ARRIVAL_SUSPICION) {
+        // What was actually on screen, not just that it was the wrong thing.
+        //
+        // This check has fired twice on CI and both times the report was a
+        // similarity score and two screen names, which is enough to know the
+        // run is void and not enough to know why. The tour asserts arrival with
+        // a `waitFor` before this ever runs, so a failure here means the
+        // `waitFor` *passed* on a screen that was not the destination — and the
+        // labels are the only thing that can say what that screen was.
+        const labels = (id.entry?.targets ?? [])
+          .map((t) => t.label).filter(Boolean).slice(0, 12).map((l) => l.slice(0, 24));
         arrivalFailures.push(
-          `${previous.name} -> ${screen.name}: similarity ${s.toFixed(2)} — the screen did not change`);
+          `${previous.name} -> ${screen.name}: similarity ${s.toFixed(2)} — the screen did not change`
+          + `\n         sensors: ${(id.entry?.sources ?? []).join('+') || 'none'}`
+          + `, settled: ${id.settled}, frame ${Math.round(Date.now() - (id.state?.capturedAt ?? Date.now()))}ms old`
+          + `\n         on screen: ${labels.length ? labels.join(' · ') : '(nothing readable)'}`);
       }
     }
     readings.push({
@@ -216,6 +229,12 @@ if (arrivalFailures.length) {
   console.error('measure the tour rather than the fingerprint. Fix the tour and re-run.');
   console.error('A `settle` step defaults to mode "stable", which returns instantly in the');
   console.error('moment before an animation begins — action steps already settle on their own.');
+  console.error('');
+  console.error('The tour asserts arrival with a `waitFor` before any reading is taken, so a');
+  console.error('failure here means that wait PASSED on a screen that was not the destination.');
+  console.error('Read the labels above before changing the tour: either the wait matched');
+  console.error('something it should not have, or the reading came off a frame older than the');
+  console.error('navigation — and those have opposite fixes.');
   process.exit(1);
 }
 

package/scripts/replay-rulings.mjs

@@ -76,6 +76,8 @@ if (baseline > 0.65) {
 const STILL_MS_THRESHOLD = 3000;
 console.log(`\nthe brief every model arm gets is ${ollama.readBrief().length} characters, read from native/supervise.swift`);
 
+const withAbstain = process.argv.includes('--abstain');
+
 const results = [];
 for (const arm of arms) {
   const judged = [];
@@ -87,6 +89,7 @@ for (const arm of arms) {
     const detail = {};
     const ruling = await supervisor.judge({
       ...r.situation,
+      mayAbstain: withAbstain,
       options: { supervisor: arm },
       // Wide on purpose. The shipped budget is 2.5s and a 14B will exceed it;
       // capping here would score the larger model on *latency* while calling it
@@ -96,7 +99,7 @@ for (const arm of arms) {
       detail,
     });
     if (!ruling) unanswered += 1;
-    judged.push({ r, ruling, detail });
+    judged.push({ r, ruling, detail, abstained: detail.kind === 'abstained' });
     process.stdout.write('.');
   }
   const answered = judged.filter((j) => j.ruling);
@@ -104,6 +107,7 @@ for (const arm of arms) {
   const lat = answered.map((j) => j.ruling.ms).filter(Number.isFinite).sort((a, b) => a - b);
   results.push({
     arm,
+    judged,
     n: rows.length,
     unanswered,
     // Scored over every situation, not only the answered ones. A judge that
@@ -131,6 +135,24 @@ for (const r of results) {
   console.log(`${r.arm.padEnd(26)} ${pct(r.accuracy).padStart(9)} ${`${r.medianMs ?? '—'}ms`.padStart(9)} ${`${r.unanswered}`.padStart(10)}`);
 }
 
+if (withAbstain) {
+  console.log(`\n--- item 100: the fourth word ---`);
+  console.log('The question is not whether it abstains. It is whether it abstains on');
+  console.log('the ones it would have got WRONG, or at random. A judge that declines');
+  console.log('uniformly has added latency and a round trip and bought nothing.\n');
+  console.log(`${'arm'.padEnd(22)} ${'answered'.padStart(9)} ${'of those'.padStart(9)} ${'abstained'.padStart(10)} ${'escalations'.padStart(12)}`);
+  console.log('-'.repeat(66));
+  for (const r of results) {
+    const answered = r.judged.filter((j) => j.ruling);
+    const right = answered.filter((j) => satisfies(j.ruling.decision, want(j.r))).length;
+    const abstained = r.judged.filter((j) => j.abstained).length;
+    console.log(`${r.arm.padEnd(22)} ${`${answered.length}/${rows.length}`.padStart(9)} ${pct(right / (answered.length || 1)).padStart(9)} ${`${abstained}`.padStart(10)} ${pct(abstained / rows.length).padStart(12)}`);
+  }
+  console.log('\n`of those` is accuracy on the questions it chose to answer. If the fourth');
+  console.log('word is working, that number is higher than the three-word accuracy above');
+  console.log('by more than the abstention rate would give by chance.');
+}
+
 console.log('\nerrors, by arm:');
 for (const r of results) {
   console.log(`  ${r.arm}`);
@@ -140,6 +162,43 @@ for (const r of results) {
   for (const [e, n] of [...seen].sort((a, b) => b[1] - a[1])) console.log(`    ${String(n).padStart(3)}x ${e}`);
 }
 
+// --- the cascade: threshold -> local model -> Claude -----------------------
+//
+// The owner's proposal, and the numbers are the only way to say whether it
+// helps: answer with the free rule where it is confident, fall through to the
+// on-device model where it is not, and only then pay a round trip.
+//
+// **A cascade needs a tier that can decline, and neither tier has one.** The
+// threshold is a comparison — it always answers. The supervisor's vocabulary is
+// three words and none of them is "I don't know". So the interesting number is
+// not "does a cascade help" but "how much would an abstain token be worth", and
+// that is item 100. This measures it directly, by letting the rule abstain in a
+// band around its own threshold and handing those to the next tier.
+const armDecisions = new Map(results.map((r) => [r.arm, r.judged]));
+console.log('\n--- cascade: the rule answers, the model covers where it abstains ---');
+console.log(`${'abstain band'.padEnd(22)} ${'rule'.padStart(6)} ${'->model'.padStart(8)} ${'cascade'.padStart(9)} ${'model calls'.padStart(12)}`);
+for (const band of [0, 250, 500, 750, 1000, 1500]) {
+  const lo = STILL_MS_THRESHOLD - band;
+  const hi = STILL_MS_THRESHOLD + band;
+  for (const arm of arms) {
+    const judged = armDecisions.get(arm) ?? [];
+    let right = 0;
+    let escalated = 0;
+    for (const [i, r] of rows.entries()) {
+      const still = r.situation.stillMs ?? 0;
+      if (band > 0 && still >= lo && still <= hi) {
+        escalated += 1;
+        const ruling = judged[i]?.ruling;
+        if (ruling && satisfies(ruling.decision, want(r))) right += 1;
+        continue;
+      }
+      if (satisfies(still > STILL_MS_THRESHOLD ? 'stop' : 'wait', want(r))) right += 1;
+    }
+    console.log(`${`+/-${band}ms -> ${arm}`.padEnd(22)} ${pct(stillRule).padStart(6)} ${`${escalated}`.padStart(8)} ${pct(right / rows.length).padStart(9)} ${`${escalated}/${rows.length}`.padStart(12)}`);
+  }
+  if (band === 0) console.log('  (band 0 = no abstention, the rule alone — every row below adds a tier)');
+}
+
 console.log('\nThis scores DECISIONS on identical inputs. It cannot score outcomes —');
 console.log('whether acting on a ruling recovered the flow is a fact about the device at');
 console.log('that moment, and belongs to whichever arm was live. See docs/EXPERIMENTS.md.');

package/src/actions.js

@@ -819,6 +819,22 @@ export async function runScript(
           fingerprint: beforeScreen?.hash ?? null,
           reason: 'verification_failed',
           candidates: [],
+          // Assumed, not read. A verdict says the step did not do what was
+          // expected; it does not say which faculty would have prevented that.
+          //
+          // Measured in the field and it matters: on an app whose controls are
+          // largely unlabeled, `no-visible-change` came overwhelmingly from
+          // tapping an inert text label whose real hit target was an invisible
+          // chevron — icon semantics, Phase 15 — while this line filed every
+          // one as evidence about sense of time, Phase 11. The tester reached
+          // the right conclusion from their own notes and our instrument
+          // disagreed with them. It was wrong.
+          //
+          // Not reclassified here, because `no-visible-change` also covers a
+          // switch moving 0.1% of the screen, which is neither faculty. Saying
+          // "assumed" is the honest answer; guessing a better-sounding reason
+          // would be the same mistake in the other direction.
+          classified: false,
           // `verification_failed` is the largest reason class in the log and it
           // was the only one carrying no intent, which made most of the corpus
           // useless for asking what kind of decision costs us. The step knows
@@ -854,6 +870,7 @@ export async function runScript(
         // Carried from the throw site where it exists, and otherwise the step's
         // own target — which is what was asked for either way.
         intent: why.intent ?? goalOf(step),
+        classified: why.classified,
         outcome: 'failed',
         wallMs: Date.now() - stepStart,
         detail: err.message,
@@ -2369,8 +2386,26 @@ async function runStep(deviceQuery, udid, step, ctx) {
         timeoutMs: step.timeoutMs ?? 8000,
         options: ctx.options,
       });
-      if (!w.satisfied) throw new Error(w.stalled ? w.live.note : `screen did not settle within ${w.waitedMs}ms`);
-      return `settled after ${w.waitedMs}ms`;
+      // Say where it is still moving — item 123.
+      //
+      // "did not settle within 25000ms" is true and unactionable, and a failed
+      // step aborts the rest of the batch, so a spinner nobody cares about can
+      // cost five steps that would have worked. The reporter who asked for this
+      // had landed on `pause` plus `continueOnError` and called it *"strictly
+      // worse than a settle that knows what to ignore"*. Knowing what to ignore
+      // is the expensive half and is not built. Saying where is nearly free —
+      // the signatures were already read to detect small changes — and it is
+      // the difference between re-planning a flow and ignoring a corner of it.
+      if (!w.satisfied) {
+        if (w.stalled) throw new Error(w.live.note);
+        throw new Error(`screen did not settle within ${w.waitedMs}ms — ${settleEvidence(w)}`);
+      }
+      // A settle that satisfied while part of the screen is still moving says
+      // so. The daemon has boxed the moving part all along and nothing read it;
+      // measured at 79s of claimed stillness on a screen animating at 85ms a
+      // frame. Not treated as a failure — see the note on `animatingNow`.
+      return `settled after ${w.waitedMs}ms`
+        + (w.animating ? ` (a ${w.animating.width}x${w.animating.height} region is still animating)` : '');
     }
     case 'waitText': {
       const target = step.value ?? step.text;
@@ -2385,10 +2420,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
           // 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)`,
-            );
+          // Satisfies the wait, for the same reason as `waitFor` above: several
+          // matches is an answer of "yes, it is here".
+          const many = err.message.match(/matched (\d+) elements/);
+          if (many) {
+            return `"${target}" is on screen (${many[1]} matches)`
+              + ' — the wait is satisfied; pass an index to act on one of them';
           }
         }
         await sleep(250);
@@ -2553,10 +2590,22 @@ async function runStep(deviceQuery, udid, step, ctx) {
           //
           // Distinguished by the tag at the throw site rather than by reading
           // the message, because "not on this screen" tags the same reason.
+          //
+          // And it **satisfies** the wait rather than failing it, which is the
+          // correction. The paragraph above had the reasoning right — ambiguous
+          // means the target is present, several times over — and then threw
+          // anyway. A `waitFor` asks one question, *has it arrived*, and two
+          // matches is a yes. Reported from the field: the batch was abandoned
+          // and three queued steps discarded on a screen that was exactly where
+          // the flow wanted to be, and the tester had to re-issue the lot with
+          // an index. The ambiguity is real and belongs in the next step's
+          // selector, not in this step's verdict.
           if (metrics.escalationOf(err)?.ambiguous) {
-            throw new Error(
-              `${err.message}\n  (not waiting: it is already on screen, and waiting cannot make it unique)`,
-            );
+            // The count comes from the message because the tag is a boolean —
+            // it marks *which kind* of ambiguity, not how many.
+            const n = err.message.match(/matches (\d+) things/)?.[1];
+            return `${query} is on screen${n ? ` (${n} matches)` : ' more than once'}`
+              + ' — the wait is satisfied; pass an index or a #ref to act on one of them';
           }
         }
         if (Date.now() >= limit) break;
@@ -2657,3 +2706,41 @@ async function runStep(deviceQuery, udid, step, ctx) {
       throw new Error(`unknown step "${step.action}"`);
   }
 }
+
+/**
+ * Why a settle gave up, in the numbers that decided it.
+ *
+ * `screen did not settle within 25008ms` names the one quantity that is never
+ * the reason, and two CI cycles went into guessing what was behind it. A wait
+ * turns on three things and the message carried none of them:
+ *
+ *   - how long the screen had actually been still when we gave up
+ *   - how much stillness was being asked for
+ *   - whether any frame arrived during the call at all
+ *
+ * *"Still for 1,200 ms of the 1,400 required"* and *"still for 135,000 ms and no
+ * frame ever arrived"* are opposite diagnoses — the first is a budget a hair too
+ * tight, the second is a stalled pipeline wearing a calm screen — and they had
+ * one sentence between them. So did *"something is animating in the top right"*.
+ *
+ * Ordered by what to do next: what is moving, then how close stillness got,
+ * then whether anything was observed, then black frames.
+ */
+export function settleEvidence(w) {
+  const parts = [];
+  const m = w.motion;
+  if (m) parts.push(`the movement is ${m.where}${m.localised ? ` (${m.share}% of it)` : ''}`);
+  if (Number.isFinite(w.stillForMs) && Number.isFinite(w.stableMsRequired)) {
+    parts.push(`still for ${w.stillForMs}ms of the ${w.stableMsRequired}ms required`);
+  }
+  // Zero frames is the loud one: a wait that observed nothing has not measured
+  // this screen, it has measured a file on disk.
+  if (Number.isFinite(w.framesSeen)) {
+    parts.push(w.framesSeen > 0
+      ? `${w.framesSeen} frame(s) arrived while waiting`
+      : 'NO frame arrived while waiting — capture, not the screen');
+  }
+  if (w.blackFrames > 0) parts.push(`${w.blackFrames} black frame(s) — see the capture wedge`);
+  return (parts.length ? parts.join('; ') : 'nothing observed')
+    + (m ? `\n${m.map}` : '');
+}

package/src/analyze.js

@@ -65,6 +65,25 @@ export function signatureDiff(a, b) {
  */
 export const CELL_CHANGE = 0.012;
 
+/**
+ * How far two *capture paths* may differ and still be looking at one screen.
+ *
+ * Not the change threshold, and the distinction matters. `signatureDiff > 0.004`
+ * asks whether a screen moved between two frames from the *same* path. This asks
+ * whether the daemon's frame and an independent `simctl` screenshot show the
+ * same thing — and they never match closely, because one is downscaled by the
+ * capture loop and the other is a full-resolution PNG scaled here.
+ *
+ * Measured on this device, which is the only reason a number appears:
+ *
+ *   same screen, two paths       0.00123  (three runs, identical to five places)
+ *   two different screens        0.68603  (before and after a home press)
+ *
+ * A separation of 550x, so the threshold is not delicate. 0.02 is sixteen times
+ * the scaling cost and thirty-four times under the signal.
+ */
+export const PATHS_AGREE = 0.02;
+
 /** The largest single-region change between two signatures, 0-1. */
 export function maxCellDelta(a, b) {
   const deltas = regionDeltas(a, b);
@@ -100,6 +119,43 @@ export function regionMap(deltas, cols = REGION_COLS) {
   return lines.join('\n');
 }
 
+/**
+ * Where the movement is, in words — item 123.
+ *
+ * A settle that gives up says only that it gave up, and the reporter who asked
+ * for this put the cost plainly: a streaming summary panel, a Lottie and a
+ * support widget never settle, so the settle fails, and because a failed step
+ * aborts the batch it takes the other five steps with it. Their workaround was
+ * `pause` plus `continueOnError`, which they called *"strictly worse than a
+ * settle that knows what to ignore"*. Knowing what to ignore is the expensive
+ * half. Saying **where** is nearly free, and it is what turns "did not settle"
+ * into "there is a spinner in the top-right and nobody cares about it".
+ *
+ * Deliberately coarse. Thirds of the screen in each axis, named the way a person
+ * would point at it, and a share so a caller can tell one spinner from a screen
+ * that is genuinely still in flight.
+ */
+export function describeMotion(deltas, cols = REGION_COLS) {
+  const total = deltas.reduce((a, b) => a + b, 0);
+  if (!deltas.length || total <= 0) return null;
+  const rows = Math.ceil(deltas.length / cols);
+  const bands = new Map();
+  const third = (i, n) => (i < n / 3 ? 0 : i < (2 * n) / 3 ? 1 : 2);
+  const DOWN = ['top', 'middle', 'bottom'];
+  const ACROSS = ['left', 'centre', 'right'];
+  deltas.forEach((d, i) => {
+    const key = `${DOWN[third(Math.floor(i / cols), rows)]}-${ACROSS[third(i % cols, cols)]}`;
+    bands.set(key, (bands.get(key) ?? 0) + d);
+  });
+  const ranked = [...bands.entries()].sort((a, b) => b[1] - a[1]);
+  const [where, amount] = ranked[0];
+  const share = Math.round((amount / total) * 100);
+  // A single band holding most of the movement is a localised animation; spread
+  // evenly, the whole screen is in flight and naming a corner would mislead.
+  if (share < 40) return { where: 'spread across the screen', share, localised: false };
+  return { where: where.replace('-', ' '), share, localised: true };
+}
+
 /** Signatures live in state.json, so they are stored as compact hex. */
 export function signatureToHex(sig) {
   return sig.map((v) => v.toString(16).padStart(2, '0')).join('');

package/src/cli.js

@@ -467,6 +467,77 @@ async function main() {
     }
 
     case 'frame': {
+      // `--fresh` captures independently of the daemon, and then says whether
+      // the two agree.
+      //
+      // This is the arbiter three field reports had to leave simframe to get.
+      // When `sim_look` served a three-hour-stale image labelled `130ms old`,
+      // the thing that finally settled it was `xcrun simctl io … screenshot` —
+      // run by hand, outside the tool, because nothing inside offered an
+      // independent read. Worse, the obvious candidate lies: `--engine` decides
+      // how to *start* a daemon, so passing `--engine=screenshot` to a read
+      // command returns the running daemon's cached frame. A tester compared
+      // the two, got byte-identical files with the same frame number, and
+      // reasonably concluded "the fallback engine is not an escape hatch".
+      //
+      // One command now answers the question the escape hatch was for: capture
+      // the screen twice by two different paths and report whether they agree.
+      if (flags.fresh) {
+        const dev = await resolveDevice(device);
+        const out = flags.out || path.join(process.cwd(), 'simframe.png');
+        await screenshot(dev.udid, out);
+        const png = fs.readFileSync(out);
+        // The daemon's own newest frame, for comparison. Absent is fine and
+        // interesting in itself: an independent capture that works while the
+        // daemon has none is exactly the wedge.
+        let cached = null;
+        try {
+          cached = await api.getFrame(device, { detail: flags.detail ?? 'normal', options });
+        } catch { /* no daemon, or it has nothing — reported below */ }
+        // Compared by *content*, never by bytes. The direct capture is a
+        // full-resolution PNG and the daemon's is downscaled, so a byte
+        // comparison says "different" every time — which is a confident wrong
+        // answer about the one question this command exists to settle. Both
+        // are decoded and reduced to the same region signature the change
+        // detector already uses, and `signatureDiff` is the same measure that
+        // decides whether a screen moved.
+        let diff = null;
+        if (cached) {
+          try {
+            const a = analyze.regionSignature(decodePng(png));
+            const b = analyze.regionSignature(decodePng(cached.png));
+            diff = analyze.signatureDiff(a, b);
+          } catch { /* an undecodable frame is reported as "could not compare" */ }
+        }
+        // The threshold the daemon itself calls a change. Below it the two
+        // paths are looking at the same screen.
+        const same = diff == null ? null : diff <= analyze.PATHS_AGREE;
+        emit(
+          flags,
+          {
+            file: out,
+            fresh: true,
+            bytes: png.length,
+            daemonSeq: cached?.state?.seq ?? null,
+            daemonAgeMs: cached?.ageMs ?? null,
+            agrees: same,
+            difference: diff == null ? null : Number(diff.toFixed(4)),
+          },
+          [
+            `${out} — captured directly from the device, ${png.length} bytes`,
+            cached
+              ? `the daemon's newest frame is #${cached.state.seq}, ${cached.ageMs}ms old`
+                + (same == null
+                  ? ' — could not be compared (one of the two would not decode)'
+                  : same
+                    ? ` — the two paths agree (difference ${diff.toFixed(4)}, under the ${analyze.PATHS_AGREE} two paths may differ by)`
+                    : ` — they DISAGREE (difference ${diff.toFixed(4)}). Two capture paths see different screens;`
+                      + ' this file is the one that bypassed the daemon. `simframe revive` re-attaches capture.')
+              : 'the daemon has no frame to compare against, while a direct capture worked',
+          ],
+        );
+        return;
+      }
       const res = await api.getFrame(device, { detail: flags.detail ?? 'normal', options });
       const out = flags.out || path.join(process.cwd(), 'simframe.png');
       fs.writeFileSync(out, res.png);
@@ -491,7 +562,9 @@ async function main() {
       } else {
         const s = res.state;
         const out = [];
-        if (!res.live.ok) out.push(`WARNING: ${res.live.note}`);
+        // Any note, not only a failing one: a dead surface reports `ok` with
+        // something important to say. See `liveness`.
+        if (res.live.note) 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}`);
@@ -546,20 +619,36 @@ async function main() {
           changedBeforeWait: Boolean(res.changedBeforeWait),
           noVisibleChange: Boolean(res.noVisibleChange),
           stalled: Boolean(res.stalled),
+          // Where it was still moving, when it never stopped — item 123.
+          //
+          // `waitFor` has computed this since it learned to, and this payload
+          // is hand-built, so the field existed and no caller could see it. I
+          // read a null here and nearly concluded the tracking was broken; it
+          // was the reporting.
+          motion: res.motion ?? null,
+          animating: res.animating ?? null,
           hash: res.state?.hash,
           seq: res.state?.seq,
         },
         () => {
           if (res.satisfied) {
             return `${res.mode === 'change' ? 'changed' : 'settled'} after ${res.waitedMs}ms — frame #${res.state.seq}` +
-              (res.changedBeforeWait ? ' (change had already happened before the call)' : '');
+              (res.changedBeforeWait ? ' (change had already happened before the call)' : '') +
+              (res.animating
+                ? `\nbut a ${res.animating.width}x${res.animating.height} region is still animating`
+                  + ' — the stillness signal is a mean and cannot see it'
+                : '');
           }
           if (res.noVisibleChange) {
             return `no visible change after ${res.waitedMs}ms — screen stable, nothing moved (the action may have had no visible effect)`;
           }
           if (res.stalled) return `capture stalled after ${res.waitedMs}ms — ${res.live.note}`;
           return `timed out after ${res.waitedMs}ms — no ${res.mode === 'change' ? 'change' : 'settle'}` +
-            (res.sawChange ? '' : '; if the change happened before this call, pass `--since` from `simframe mark`');
+            (res.sawChange ? '' : '; if the change happened before this call, pass `--since` from `simframe mark`') +
+            (res.motion
+              ? `\nthe movement is ${res.motion.where}`
+                + `${res.motion.localised ? ` (${res.motion.share}% of it)` : ''}:\n${res.motion.map}`
+              : '');
         },
       );
       process.exitCode = res.satisfied ? 0 : 1;
@@ -1106,13 +1195,31 @@ async function main() {
 
     case 'supervisions': {
       const dev = await resolveDevice(flags.device);
-      const records = metrics.readSupervisions(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      // `--session` works here now, and did not before.
+      //
+      // Reported twice from the field: two different session ids returned
+      // byte-identical output while `escalations --session` filtered correctly.
+      // A flag that exists on one command and is silently inert on its sibling
+      // is worse than an absent one — this command's own footer warns that the
+      // counts pool multiple agents and then offered no way to unpool them.
+      const session = flags.session === true
+        ? metrics.sessionId()
+        : (flags.session ? String(flags.session) : null);
+      const all = metrics.readSupervisions(dev.udid, { limit: flags.last ? num(flags.last) : undefined });
+      const records = session ? all.filter((r) => r?.session_id === session) : all;
       const b = metrics.supervisionBreakdown(records);
       if (flags.out) store.writeAtomic(String(flags.out), `${JSON.stringify({ ...b, records }, null, 2)}\n`);
       emit(flags, { ...b, records: flags.verbose ? records : undefined }, [
         `${b.total} supervisor ruling${b.total === 1 ? '' : 's'} on ${dev.name}`,
-        b.total ? '' : 'Nothing has been judged on this device yet. The supervisor is off unless'
-          + ' SIMFRAME_SUPERVISOR=apple, and a ruling is only recorded when a step actually fails.',
+        // "Nothing here" and "nothing matched your filter" are different
+        // answers, and the first one told a reader the supervisor had never
+        // run on a device holding 111 rulings.
+        b.total
+          ? null
+          : (all.length
+            ? `no ruling in this log belongs to session ${session} — the device has ${all.length}.`
+            : 'Nothing has been judged on this device yet. The supervisor is off unless'
+              + ' SIMFRAME_SUPERVISOR=apple, and a ruling is only recorded when a step actually fails.'),
         ...Object.entries(b.decision_to_outcome)
           .sort((a, c) => c[1] - a[1])
           .map(([k, n]) => `  ${k.padEnd(28)} ${String(n).padStart(4)}`),
@@ -1128,8 +1235,12 @@ async function main() {
               ? ` — ${b.p95_unknown} ruling(s) are on edges with no p95, so they cannot take part in 101's comparison`
               : '')
           : null,
+        session && all.length !== records.length
+          ? `filtered to session ${session}: ${records.length} of ${all.length} ruling(s)`
+          : null,
         b.sessions.length > 1
           ? `WARNING ${b.sessions.length} sessions are pooled here; two agents on one device write one file`
+            + ' — narrow with --session (this process) or --session=<id>'
           : null,
       ].filter((l) => l !== null).join('\n'));
       break;
@@ -1148,10 +1259,29 @@ async function main() {
         ...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])
+          .map((r) => {
+            const n = b.by_reason[r];
+            const read = b.classified_by_reason?.[r] ?? 0;
+            // A faculty is only named for the part of a reason that was read
+            // off the failure. The rest is a count of things nothing could
+            // classify, and naming a phase against it is advice with nothing
+            // behind it — which is how this report came to tell a tester that
+            // their unlabeled-control problem was a timing problem.
+            const assumed = b.assumed_by_reason?.[r] ?? 0;
+            const named = metrics.BUILT_FACULTIES.has(metrics.FACULTY[r])
               ? `not removed by: ${metrics.FACULTY[r]} [built]`
-              : `would be removed by: ${metrics.FACULTY[r]}`)),
+              : `would be removed by: ${metrics.FACULTY[r]}`;
+            let verdict;
+            if (read > 0) {
+              verdict = named + (read < n ? ` (on the ${read} of ${n} whose reason was read)` : '');
+            } else if (assumed > 0) {
+              verdict = 'reason assumed, not read — no faculty can be named from these';
+            } else {
+              // Neither read nor assumed: the log predates the distinction.
+              verdict = `${named} — but these records predate the check, so treat it as untested`;
+            }
+            return `  ${r.padEnd(20)} ${String(n).padStart(4)}   ${verdict}`;
+          }),
         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
@@ -1525,9 +1655,38 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       // machine could be doing better and silently is not; a driver someone
       // selected on purpose is neither silent nor a surprise.
       const axState = !ax.available ? 'optional' : ax.name === 'simframed' || ax.chosen ? 'ok' : 'warn';
-      add(`accessibility tree (${d.name})`, axState,
-        ax.available ? `${ax.name}: ${ax.version}` : `unavailable: ${ax.reason}`,
+      // Prove a round trip, not a presence — the same correction this file
+      // already made for the supervisor, never carried across to here.
+      //
+      // A CI run read the screen eighteen times and every single reading came
+      // back `ocr` with no `ax` at all, while this check said `ok` because a
+      // driver was configured. It is configured; it answers with nothing. Six
+      // minutes later the fingerprint step failed with a distribution mystery,
+      // and the layer that had actually died was named nowhere. Asking the tree
+      // for the current screen costs one read (~50ms) and turns that into a
+      // first-minute failure with the right sentence on it.
+      let axCount = null;
+      if (ax.available) {
+        try {
+          axCount = (await input.describeAll(d.udid)).length;
+        } catch {
+          axCount = 0;
+        }
+      }
+      add(`accessibility tree (${d.name})`,
+        // `warn`, not `fail`: a genuinely empty screen exists — a springboard
+        // mid-boot, a black frame — and a hard error on one would cry wolf.
+        // The count is exported so a caller that knows the screen is not empty
+        // can assert on it, which is what CI does.
+        ax.available && axCount === 0 ? 'warn' : axState,
+        ax.available
+          ? `${ax.name}: ${ax.version}`
+            + (axCount === 0
+              ? ' — but it returned NO elements for the current screen, so every read is OCR alone'
+              : axCount != null ? `; ${axCount} element(s) on the current screen` : '')
+          : `unavailable: ${ax.reason}`,
         { key: 'ax.driver', value: ax.name });
+      if (axCount != null) add(null, null, null, { key: 'ax.elements', value: axCount });
     }
     if (probed.length) {
       const t0 = Date.now();
@@ -1554,6 +1713,13 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       for (const d of probed) {
         const live = api.liveness(d.udid, (await api.getState(d.udid)).state);
         if (live.stalled) add(`capture health (${d.name})`, 'fail', live.note, { key: 'capture.stalled', value: true });
+        // A `warn` rather than a `fail`, because a genuinely inert screen is
+        // possible and this is a contradiction between two numbers rather than
+        // a proven fault. It is still the loudest thing `doctor` can say about
+        // the failure that made a tester report a false application state.
+        else if (live.suspectSurface) {
+          add(`capture surface (${d.name})`, 'warn', live.note, { key: 'capture.suspectSurface', value: true });
+        }
       }
     }
   } catch (err) {
@@ -1594,11 +1760,14 @@ async function doctor({ json = false, strict = false, device, options = {} } = {
       warnings: warned.length,
       optional: optional.length,
       ...flat,
-      checks: checks.map(({ name, level, detail }) => ({ name, level, detail })),
+      checks: checks.filter((c) => c.name).map(({ name, level, detail }) => ({ name, level, detail })),
     }, null, 2));
   } else {
     const mark = { ok: 'ok  ', warn: 'WARN', fail: 'FAIL', optional: '--  ' };
-    for (const c of checks) console.log(`${mark[c.level]} ${c.name.padEnd(24)} ${c.detail}`);
+    // A nameless entry is data for `--json` and not a line for a reader — the
+    // element count belongs beside the layer it describes, not on a row of its
+    // own.
+    for (const c of checks) if (c.name) console.log(`${mark[c.level]} ${c.name.padEnd(24)} ${c.detail}`);
     if (warned.length) {
       console.log(`\n${warned.length} layer(s) degraded. simframe still works, but not at full speed or coverage:`);
       for (const c of warned) console.log(`  - ${c.name}: ${c.detail}`);

package/src/fingerprint.js

@@ -72,8 +72,17 @@ import * as regions from './regions.js';
  *     graph merged them. Both bounds are absolute now. Screens that were
  *     missed at 7 hash differently at 8, and unlike a stale hash that matches
  *     nothing, these matched the *wrong* thing.
+ *
+ * 9 — nothing in this file changed. The element list it is given did: item 122
+ *     stopped dropping accessibility nodes that have no name, so a screen with
+ *     an icon-only control now carries a token for it that it did not carry
+ *     before. That is a better identity — a nav bar with an overflow menu and
+ *     one without are not the same screen — and it is still a different hash
+ *     for the same screen, which is what this number exists to declare. The
+ *     lesson worth keeping is that the rules version is not a version of *this
+ *     file*; it is a version of the token set, and the token set has an input.
  */
-export const TOKEN_RULES_VERSION = 8;
+export const TOKEN_RULES_VERSION = 9;
 
 /** Frames are quantised to this, so sub-pixel drift and a nudged row do not matter. */
 export const GRID = 24;