simframe 0.9.0 → 0.10.0

package/src/index.js

@@ -9,6 +9,9 @@ import { decodePng, encodePng, scaleBitmap } from './png.js';
 import {
   REGION_COLS,
   hexToSignature,
+  isBlackFrame,
+  maxCellDelta,
+  CELL_CHANGE,
   regionDeltas,
   regionMap,
   signatureDiff,
@@ -398,6 +401,80 @@ export function resolveBaseline(state, since) {
   return { kind: 'unmatched', requested: key };
 }
 
+/**
+ * Is the baseline describing a screen that had already finished moving?
+ *
+ * Pure, so the rule can be argued with in a test rather than only observed on
+ * a device. The full reasoning is at the call site in `waitFor`; the short
+ * version is that stillness cannot accumulate in the milliseconds between a
+ * dispatch returning and a wait beginning, so a screen that already differs
+ * from the baseline *and* has already been at rest for the whole stillness
+ * window changed for some earlier reason.
+ */
+/** The newest frame's region signature, which the state already carries. */
+function currentSig(state) {
+  const h = state?.history;
+  if (!h?.length) return null;
+  const newest = h.find((x) => x.seq === state.seq) ?? h[h.length - 1];
+  return newest?.sig ?? null;
+}
+
+/**
+ * The longest pause inside a transition, measured after the transition is over.
+ *
+ * This is the unbiased half of the estimator that was reverted in Phase 11, and
+ * the difference is entirely about *when* the measurement stops.
+ *
+ * The biased version accumulated the statistic from inside the wait: the
+ * longest stretch of stillness the wait itself happened to observe. Feed that
+ * back into how long the next wait runs and it eats itself — a wait that ends
+ * early never sees the pauses that come later, so the gaps read as zero, the
+ * window ratchets down, the next wait ends earlier still, and eventually a
+ * settle returns mid-transition and the graph learns a screen it never reached.
+ * That is not a theory; it corrupted this device's graph in one afternoon.
+ *
+ * This one reads the frame history *after* the fact, over a window whose end is
+ * not decided by the wait. The frames are already on disk with their timestamps
+ * and their hashes, so the true profile of a transition is recoverable as long
+ * as the history still reaches back to it.
+ *
+ * That last condition is the whole reason this returns null rather than a
+ * number: the ring is bounded, and during fast motion it holds a second or two.
+ * A partial window would produce a *shorter* gap than really occurred, which is
+ * the exact direction of the bias being removed. Reporting nothing is the only
+ * honest answer to a question the evidence cannot reach.
+ */
+export function longestQuietGap(history, sinceMs, untilMs = Date.now()) {
+  if (!Array.isArray(history) || history.length < 2) return null;
+  const frames = history
+    .filter((f) => Number.isFinite(f?.at) && f.at >= sinceMs && f.at <= untilMs)
+    .sort((a, b) => a.at - b.at);
+  if (frames.length < 2) return null;
+  // The history has to reach back to the action itself. One frame interval of
+  // slack, because the frame that captures the moment of the action is not
+  // required to land exactly on it.
+  const span = frames[1].at - frames[0].at;
+  if (frames[0].at > sinceMs + Math.max(250, span)) return null;
+
+  let longest = 0;
+  let lastChangeAt = frames[0].at;
+  for (let i = 1; i < frames.length; i += 1) {
+    if (frames[i].hash !== frames[i - 1].hash) {
+      longest = Math.max(longest, frames[i].at - lastChangeAt);
+      lastChangeAt = frames[i].at;
+    }
+  }
+  // The quiet after the last change is not a pause *inside* the transition —
+  // it is the transition being over, which is what a settle already measures.
+  return longest;
+}
+
+export function baselineAlreadySettled({ mode, changedAtStart, stableForMs, stableMs } = {}) {
+  if (mode === 'stable' || !changedAtStart) return false;
+  if (!Number.isFinite(stableForMs) || !Number.isFinite(stableMs)) return false;
+  return stableForMs >= stableMs;
+}
+
 function compareToBaseline(state, baseline) {
   if (!baseline) return null;
   if (baseline.kind === 'history') {
@@ -497,6 +574,10 @@ export async function getState(deviceQuery, { since, options, inputHealth = fals
     map: regionMap(state.regions || [], REGION_COLS),
     since: compareToBaseline(state, resolveBaseline(state, since)),
     live: liveness(device.udid, state),
+    // Costs 32 integer comparisons on a signature already computed, and it is
+    // the difference between "the screen is calm" and "the display stopped
+    // rendering" — which looked identical to everything above this line.
+    black: isBlackFrame(currentSig(state)),
     // Off by default and asked for by the state commands only. A flow step
     // calls getState twice, and the fix for a stale session runs before every
     // action anyway (input.ensureFreshSession) — this is the report, not the
@@ -568,7 +649,7 @@ export async function waitFor(
   const p = store.paths(device.udid);
   const requested = since ?? baselineHash;
   const resolved = resolveBaseline(first, requested);
-  const baselineHashValue =
+  let baselineHashValue =
     resolved?.kind === 'history' ? resolved.entry.hash : (requested ?? first.hash);
   const baselineResolved = resolved?.kind === 'history' || requested == null;
 
@@ -590,10 +671,62 @@ export async function waitFor(
    */
   let quietGapMs = 0;
   let quietRun = 0;
+  /**
+   * The baseline's own signature, for changes the mean cannot see.
+   *
+   * Only when the baseline was found in the frame history — a hash we cannot
+   * place has no signature to compare against, and guessing one would be worse
+   * than not looking.
+   */
+  const baselineSig = resolved?.kind === 'history' && resolved.entry?.sig
+    ? hexToSignature(resolved.entry.sig)
+    : (requested == null ? hexToSignature(currentSig(first) ?? '') : null);
+  let smallChange = false;
+  /** Frames the display was not rendering at all. See `isBlackFrame`. */
+  let blackFrames = 0;
+  let blackSinceStart = null;
   let lastHash = first.hash;
   let sawChange = mode === 'stable' || first.hash !== baselineHashValue;
   const changedAtStart = sawChange && mode !== 'stable';
 
+  /**
+   * The baseline describes a screen that has already finished moving.
+   *
+   * `since` means "the screen as it was before the action", and the whole
+   * reliability of these scripts rests on it being captured *before* rather
+   * than after — a baseline sampled afterwards is the commonest way to wait for
+   * a change that already happened. What was missing is the other end of it:
+   * time also passes between capturing the baseline and dispatching the action,
+   * and in a flow step that gap holds a `locate`, a perception pass and a
+   * settle wait — hundreds of milliseconds, not microseconds.
+   *
+   * So a transition can begin *and finish* in that gap, and then `sawChange` is
+   * true at wait start because of the previous action's animation. Measured:
+   * `tap Accessibility` returned `settled 124ms` against a 500 ms stillness
+   * window, the screen had never left the Settings root, and the graph recorded
+   * `root -> root` as a verified edge — count 11, changedOutcomes 5, flipping
+   * between the real destination and itself all day.
+   *
+   * The test is unambiguous rather than clever: the screen differs from the
+   * baseline *and has already been at rest for the full stillness window*.
+   * Stillness cannot have accumulated in the milliseconds between a dispatch
+   * returning and this call starting, so whatever changed, changed and settled
+   * before we looked, and it is not this action's doing. Re-baseline to what is
+   * actually on screen and wait for a further change — which is what the caller
+   * asked for and what a stale hash prevented.
+   *
+   * A screen that differs and is *still moving* is left alone: that is
+   * genuinely ambiguous, and after an action the usual reading is the right
+   * one.
+   */
+  const staleBaseline = baselineAlreadySettled({
+    mode, changedAtStart, stableForMs: first.stableForMs, stableMs,
+  });
+  if (staleBaseline) {
+    baselineHashValue = first.hash;
+    sawChange = false;
+  }
+
   const done = (satisfied, extra = {}) => ({
     device,
     state: last,
@@ -602,6 +735,15 @@ export async function waitFor(
     quietGapMs,
     sawChange,
     changedBeforeWait: changedAtStart,
+    // Something moved, but only in one region — a control changing state
+    // rather than a screen changing.
+    smallChange,
+    staleBaseline,
+    blackFrames,
+    // Said as an observation, never as a diagnosis: a screen can be black
+    // because the app drew black. What makes it the capture wedge is that it
+    // stays black while input is being delivered, and the caller knows that.
+    blackMs: blackSinceStart ? Date.now() - blackSinceStart : 0,
     baselineHash: baselineHashValue,
     baselineResolved,
     waitedMs: Date.now() - startedAt,
@@ -617,8 +759,44 @@ export async function waitFor(
       const live = liveness(device.udid, state);
       if (!live.ok) return done(false, { stalled: true });
 
+      // A black frame is not evidence, in either direction.
+      //
+      // The capture wedge leaves every frame black while the whole capture path
+      // reports success, so before this a settle read the black screen as a
+      // change (the hash differs from anything) and then as a calm one (nothing
+      // moves), and returned `ok` for an action nobody could see the result of.
+      // It self-recovers most times, so the useful behaviour is to keep waiting
+      // rather than to conclude.
+      const black = isBlackFrame(currentSig(state));
+      if (black) {
+        blackFrames += 1;
+        blackSinceStart = blackSinceStart ?? Date.now();
+        await sleep(60);
+        continue;
+      }
+      blackSinceStart = null;
+
       if (!sawChange && state.hash !== baselineHashValue) sawChange = true;
 
+      // A change too small for the whole-screen mean to see.
+      //
+      // A switch flipping moves one cell of thirty-two by 0.043 and the mean by
+      // 0.0013 — a third of the threshold — so every switch, radio dot,
+      // checkbox and segment highlight was an action that "changed nothing",
+      // and `no-visible-change` is a verdict that escalates. See
+      // analyze.CELL_CHANGE for the measured gap this sits in.
+      //
+      // Deliberately feeding `sawChange` and *not* stillness: `stableForMs`
+      // stays on the mean, because a blinking text caret is a small localised
+      // change and a screen with a cursor would otherwise never settle.
+      if (!sawChange && baselineSig) {
+        const sig = currentSig(state);
+        if (sig && maxCellDelta(hexToSignature(sig), baselineSig) > CELL_CHANGE) {
+          sawChange = true;
+          smallChange = true;
+        }
+      }
+
       // A pause that turned out not to be the end of the transition. Only
       // pauses followed by more movement count: the quiet at the end of a
       // settle is the answer, not a gap.
@@ -985,7 +1163,11 @@ export async function locate(
           `"${query}" matches ${outcome.alternatives.length} things on this screen — say which, or pass index: ${list}`,
         ),
         'ambiguous_intent',
-        { candidates: outcome.alternatives },
+        // Present, several times over — as opposed to absent, which also tags
+        // ambiguous_intent when the screen was one we thought we knew. A
+        // waiting caller needs the difference: more time cannot make a thing
+        // unique, and it can make an absent thing arrive.
+        { candidates: outcome.alternatives, ambiguous: true },
       );
     }
     if (outcome.status === 'ok') {
@@ -1039,6 +1221,38 @@ export async function locate(
  */
 export const STRUCTURAL_SETTLE_MS = 300;
 
+/**
+ * How much of the structural window is still owed, given when the last sample's
+ * frame was captured.
+ *
+ * This was `sleep(300)` between the two readings, and unlike every other fixed
+ * wait in the engine it cannot be replaced by waiting for a signal — because
+ * there is no signal. The race it guards is a screen whose *pixels* have gone
+ * still while its structure has not: a list whose spinner has gone and whose
+ * rows have not landed is perfectly quiet and structurally wrong, so the settle
+ * detector, which watches pixels, has nothing to report. Only elapsed time
+ * separates the two readings.
+ *
+ * What can be fixed is that the wait was *additional*. The guarantee wanted is
+ * 300 ms between the frames the two samples read; the code slept 300 ms after a
+ * sample that had already spent an unbounded settle wait and a full perception
+ * pass getting there. On a screen that took a second to go quiet the separation
+ * was already there and the sleep bought nothing but a second of it. So credit
+ * what has passed and wait only for the remainder — the same guarantee, and
+ * usually none of the sleep.
+ *
+ * The window itself is per-screen learnable, and worth noting that its
+ * estimator has the *opposite* feedback sign to the one that corrupted the
+ * graph: a window too short produces disagreeing samples, which lengthens it.
+ * Self-correcting rather than self-reinforcing. It still waits on the
+ * perception eval harness, because "the samples agreed" is only evidence the
+ * window was long enough if the readings themselves are trustworthy.
+ */
+export function structuralSettleOwed(capturedAt, now = Date.now(), windowMs = STRUCTURAL_SETTLE_MS) {
+  if (!Number.isFinite(capturedAt)) return windowMs;
+  return Math.max(0, Math.min(windowMs, windowMs - (now - capturedAt)));
+}
+
 /**
  * How long identity will wait for pixels to go quiet.
  *
@@ -1122,7 +1336,8 @@ export async function screenIdentity(deviceQuery, { options, confirmNovel = true
   // Nothing recognises this, or the pixels have not gone quiet. Either way, make
   // it prove it is the same screen twice running before it becomes a node.
   for (let i = 1; i < STRUCTURAL_SETTLE_SAMPLES; i += 1) {
-    await sleep(STRUCTURAL_SETTLE_MS);
+    const owed = structuralSettleOwed(identity.state?.capturedAt);
+    if (owed > 0) await sleep(owed);
     const again = await read({ fresh: true });
     // Two readings agree if they are the same screen — the same test identity
     // itself uses. Demanding an identical hash is a stricter question than the

package/src/input.js

@@ -248,6 +248,11 @@ export function elementToNode(e) {
     type: e.role ?? null,
     identifier: e.identifier ?? null,
     enabled: e.state?.enabled ?? null,
+    // The daemon batches AXSelected and AXFocused alongside AXEnabled and has
+    // since 0.6.0. This converter took one of the three, and it is the one on
+    // the path that actually runs — `normalizeNode` below is the idb fallback.
+    selected: e.state?.selected ?? null,
+    focused: e.state?.focused ?? null,
     frame: e.frame ?? null,
     raw: e,
   };
@@ -273,6 +278,12 @@ function normalizeNode(node) {
     type: node.type ?? node.AXType ?? null,
     identifier: node.AXUniqueId ?? node.identifier ?? null,
     enabled: node.AXEnabled ?? node.enabled ?? null,
+    // The daemon has asked the tree for AXSelected and AXFocused since 0.6.0 —
+    // they are two of the eight attributes in its batched round trip — and this
+    // function dropped both. `view.renderRow` has printed `selected` for as
+    // long as it has existed, against a field nobody set.
+    selected: node.AXSelected ?? node.selected ?? null,
+    focused: node.AXFocused ?? node.focused ?? null,
     frame: frame
       ? {
           x: frame.x ?? frame.X ?? 0,
@@ -506,19 +517,52 @@ export async function sessionHealth(udid) {
 }
 
 /**
- * Rebuild the session if the device outlived it. Once per process, per device.
+ * Should this staleness be acted on, given what has already been rebuilt?
+ *
+ * Pure, and separate from the check because the *key* is the whole bug. This
+ * gate used to be a set of udids — "once per process, per device" — and the
+ * reasoning was to avoid statting on every action. What it actually bought was
+ * that the feature could not fire in the one process that matters. A CLI
+ * command is a new process every time, so per-process is per-call there and
+ * the gate never showed; the MCP server is a single process that lives for a
+ * whole session, so it checked once, at the first action, and then never
+ * again — and a device that reboots *mid-session* is precisely the case this
+ * exists to catch. Reported from a real session: capture kept working, input
+ * died, every tap returned `ok`, and about ten calls went into two wrong
+ * conclusions about the app.
+ *
+ * The right key is the boot the rebuild was for. One attempt per device boot:
+ * enough that a failed rebuild does not retry on every tap forever, and not so
+ * much that the next boot is invisible.
+ */
+export function shouldRebuildSession({ stale, bootedAt }, rebuiltFor) {
+  if (!stale) return false;
+  // A boot we cannot date cannot be memoised against, and re-attempting on
+  // every action would be worse than not detecting it. sessionStaleness only
+  // reports stale with a finite bootedAt, so this is a belt, not a case.
+  if (!Number.isFinite(bootedAt)) return false;
+  return rebuiltFor !== bootedAt;
+}
+
+/**
+ * Rebuild the session if the device outlived it. Once per device boot.
  *
  * Rebuild, and retry nothing: this runs *before* the action, so the action is
  * delivered on a session known to be current. Retrying afterwards is how an
  * action fires twice, which is the hazard the verify barrier exists to
  * prevent — and it is why the existing recovery covers hardware buttons only.
+ *
+ * The check now runs on every dispatch rather than once. It costs two small
+ * `readJson`s and, at most every three seconds, one stat — `bootedAtCached`
+ * already caps the part that was expensive, which is what made the
+ * once-per-process gate unnecessary as well as wrong.
  */
-const freshened = new Set();
+const rebuiltForBoot = new Map();
 export async function ensureFreshSession(udid) {
-  if (!udid || freshened.has(udid)) return null;
-  freshened.add(udid);
+  if (!udid) return null;
   const health = await sessionHealth(udid);
-  if (!health.stale) return null;
+  if (!shouldRebuildSession(health, rebuiltForBoot.get(udid))) return null;
+  rebuiltForBoot.set(udid, health.bootedAt);
   const rebuilt = await resetSession(udid);
   return { ...health, rebuilt };
 }

package/src/matching.js

@@ -59,7 +59,25 @@ export function nameScore(name, query) {
   const q = norm(query);
   if (!n || !q) return 0;
   if (n === q) return 1;
-  if (n.startsWith(q) || q.startsWith(n)) return 0.86;
+  // A prefix match is only as good as the share it covers, and this branch had
+  // to be taught that twice.
+  //
+  // `n.startsWith(q)` — the name begins with the query, "Acce" for
+  // "Accessibility" — is the ordinary case and keeps most of its score: a
+  // prefix of a name is how people abbreviate. `q.startsWith(n)` is the
+  // opposite direction, where the *name* is a fragment of the query, and it
+  // returned the same flat 0.86 no matter how little of the query it was. So
+  // the section-index letter "S" scored 0.86 against the query "Search" and
+  // beat the search field's own label "Q Search" at 0.585 — and simframe
+  // tapped a scrubber and typed into it.
+  //
+  // The sibling branch below already carries this lesson in a comment about
+  // "back" matching a list row. Only one of the two had learned it. Both scale
+  // now, and the floor differs by direction on purpose: a query that is a
+  // prefix of a name is usually deliberate, while a name that is a fragment of
+  // the query is usually a coincidence, and one character is always one.
+  if (n.startsWith(q)) return 0.86 * Math.max(PREFIX_FLOOR, Math.min(1, q.length / n.length + 0.35));
+  if (q.startsWith(n)) return 0.8 * Math.max(0.15, n.length / q.length);
   // A substring match is only as good as the share of the name it covers.
   // Without this, "back" scores 0.78 against a two-hundred-character list row
   // that happens to contain "Back of House", and beats the actual back button.
@@ -76,7 +94,31 @@ export function nameScore(name, query) {
   if (distance > cap) return 0;
   const longest = Math.max(n.length, q.length);
   const similarity = 1 - distance / longest;
-  return similarity >= 0.7 ? similarity * 0.72 : 0;
+  if (similarity >= 0.7) return similarity * 0.72;
+  // Last tier: OCR read a confusable character.
+  //
+  // Language correction is deliberately off, which is right for labels and
+  // wrong for exactly this. Measured on a real app, `(All)` reads back as
+  // `(AII)` and would fail an assert against the string it is; capital-I,
+  // lowercase-l, the digit one and a pipe are one shape in most UI fonts, as
+  // are capital-O and zero.
+  //
+  // Deliberately the *last* tier and discounted, not part of `norm`. Folding
+  // in `norm` would make it change what an exact match means — "Log in" and
+  // "1og in" would become the same string everywhere — and identity is not
+  // something to be fuzzy about. Here it only ever rescues a comparison that
+  // had already scored zero.
+  const foldedScore = confusableFold(n) === confusableFold(q) ? 0.62 : 0;
+  return foldedScore;
+}
+
+/** One shape per glyph family, for comparison only. Never for identity. */
+export function confusableFold(s) {
+  return String(s ?? '')
+    .replace(/[il1|!]/gi, '1')
+    .replace(/[o0]/gi, '0')
+    .replace(/[s5]/gi, '5')
+    .replace(/[b8]/gi, '8');
 }
 
 function synonymGroup(query) {
@@ -159,6 +201,17 @@ export function rank(targets, intent, { screen } = {}) {
 export const AMBIGUITY_MARGIN = 0.08;
 /** Below this, no candidate is worth acting on. */
 export const MINIMUM_SCORE = 0.45;
+/**
+ * How much of a name's score survives scaling a prefix by its coverage.
+ *
+ * Tied to `MINIMUM_SCORE` rather than chosen: at 0.5 the shortest useful
+ * abbreviation — "Ac" for "Accessibility" — scored 0.433 and fell *below* the
+ * threshold to resolve at all, which would have turned a ranking fix into a
+ * feature removal. 0.6 puts the worst case at 0.516, comfortably resolvable and
+ * still well under a fuller match. The unit test asserts the relationship so
+ * the cliff cannot come back by someone tuning one of the two numbers.
+ */
+export const PREFIX_FLOOR = 0.6;
 
 /**
  * How close two tap points have to be to mean the same control.

package/src/metrics.js

@@ -40,8 +40,16 @@ export const FACULTY = {
   no_plan: 'exploration (Phase 14)',
 };
 
-/** Faculties that exist. Empty until Phase 11 lands the first one. */
-export const BUILT_FACULTIES = new Set();
+/**
+ * Faculties that exist.
+ *
+ * Phase 11 landed the first one, so `verification_failed` no longer maps to
+ * something unbuilt — which changes what those records *mean*. Before, they
+ * were a queue waiting on a phase. Now they are evidence that the phase which
+ * shipped is not sufficient, and that is a more useful thing for the log to be
+ * able to say than a count of things nobody has written yet.
+ */
+export const BUILT_FACULTIES = new Set(['sense of time (Phase 11)']);
 
 function metricPaths(udid) {
   const dir = store.deviceDir(udid);
@@ -111,9 +119,15 @@ export const readFlows = (udid, opts) => readJsonl(metricPaths(udid).flows, opts
  * matching error strings at the boundary — a regexed message is a reason that
  * silently becomes "unknown" the day somebody rewords it.
  */
-export function tag(err, reason, { candidates = [], tried = [] } = {}) {
+export function tag(err, reason, { candidates = [], tried = [], ambiguous = false } = {}) {
   if (!REASONS.includes(reason)) throw new Error(`not an escalation reason: ${reason}`);
-  err.escalation = { reason, candidates, tried };
+  // `ambiguous` is narrower than the reason, and that is the point. Two very
+  // different failures both tag `ambiguous_intent`: the target is on screen
+  // several times over, and the target is not on screen at all on a screen we
+  // thought we knew. Only the first is resolvable by *choosing*, and only the
+  // first tells a waiting caller that waiting is pointless — the thing it is
+  // waiting for has already arrived.
+  err.escalation = { reason, candidates, tried, ambiguous };
   return err;
 }
 
@@ -213,8 +227,50 @@ export function fingerprintNow(udid, screenmap) {
  * measurement's clothes, and every number in this project is supposed to say
  * where it came from.
  */
+/**
+ * Which run of which program wrote a record.
+ *
+ * The log is per-device and, until now, anonymous — so two agents driving one
+ * booted simulator wrote one interleaved file with no way to separate them.
+ * Measured on the bench device in a single evening: 57 records to 81, a third
+ * of the new ones naming screens from an app the suite has never launched.
+ *
+ * That is not a corrupted file, it is a corrupted instrument. CLAUDE.md makes
+ * the reason breakdown of this log the thing that chooses which faculty gets
+ * built next, and a breakdown that silently pools two sessions errs toward
+ * whichever of them made more mistakes — which is not the same question as
+ * which faculty is missing.
+ *
+ * A pid alone would not do: pids are reused, and the useful grouping is "one
+ * agent's run", which for the MCP server is the life of the process and for
+ * the CLI is a single command. So: the start time, the pid, and a random tail,
+ * computed once per process. `client` says what kind of process it was, since
+ * "the MCP server did this" and "somebody ran a CLI command" deserve different
+ * readings of the same reason.
+ *
+ * Deliberately not a device id, a username, or anything about the machine. This
+ * file is committed to a public repo in summary form, and the question it has
+ * to answer is "was this all one agent", which needs no identity to answer.
+ */
+const SESSION_ID = `${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+
+/** How this process is being used, for reading a breakdown afterwards. */
+function clientKind() {
+  const argv = process.argv.join(' ');
+  if (/\bmcp\b/.test(argv)) return 'mcp';
+  if (/bench-hpi|scripts\//.test(argv)) return 'script';
+  if (/cli\.js|\bsimframe\b/.test(argv)) return 'cli';
+  return 'library';
+}
+const CLIENT = clientKind();
+
+/** The session this process's records belong to. Exported for `escalations`. */
+export const sessionId = () => SESSION_ID;
+export const clientName = () => CLIENT;
+
 export function recordEscalation(udid, {
   flowId = null,
+  flowName = null,
   stepIndex = null,
   fingerprint = null,
   reason,
@@ -229,7 +285,13 @@ export function recordEscalation(udid, {
   if (!OUTCOMES.includes(outcome)) throw new Error(`not an escalation outcome: ${outcome}`);
   const record = {
     timestamp: new Date().toISOString(),
+    // Added after the log turned out to pool two agents' work invisibly. Both
+    // are cheap and neither is derivable afterwards, which is the test for
+    // whether a field belongs in a log at all.
+    session_id: SESSION_ID,
+    client: CLIENT,
     flow_id: flowId,
+    flow_name: flowName,
     step_index: stepIndex,
     screen_fingerprint: fingerprint,
     reason,
@@ -408,14 +470,31 @@ export function hpi({ flows, baselines = {} }) {
  * rate is 1.0 by construction and says nothing. The per-reason breakdown is
  * the part that decides the next phase, and it is informative today.
  */
-export function breakdown(records) {
+export function breakdown(records, { session = null, flow = null } = {}) {
   const byReason = {};
   for (const r of REASONS) byReason[r] = 0;
   const byScreen = new Map();
   const byOutcome = {};
+  const bySession = new Map();
+  const byFlow = new Map();
   let avoidable = 0;
-  for (const r of records) {
+  let unattributed = 0;
+  // Filtering happens here rather than at the call site so `total` and every
+  // rate below it describe the same set of records.
+  const kept = records.filter((r) => (session ? r?.session_id === session : true))
+    .filter((r) => (flow ? r?.flow_name === flow : true));
+  for (const r of kept) {
     if (!REASONS.includes(r?.reason)) continue;
+    // Records written before sessions were recorded cannot be attributed, and
+    // saying how many there are is the difference between a breakdown that
+    // pools two agents and one that says it might be.
+    if (r.session_id) {
+      const key = `${r.session_id}|${r.client ?? '?'}`;
+      bySession.set(key, (bySession.get(key) ?? 0) + 1);
+    } else {
+      unattributed += 1;
+    }
+    if (r.flow_name) byFlow.set(r.flow_name, (byFlow.get(r.flow_name) ?? 0) + 1);
     byReason[r.reason] += 1;
     byOutcome[r.outcome] = (byOutcome[r.outcome] ?? 0) + 1;
     // Already avoided locally, so not avoidable by anything unbuilt.
@@ -423,9 +502,25 @@ export function breakdown(records) {
     const key = r.screen_fingerprint ?? '(no fingerprint)';
     byScreen.set(key, (byScreen.get(key) ?? 0) + 1);
   }
-  const total = records.filter((r) => REASONS.includes(r?.reason)).length;
+  const total = kept.filter((r) => REASONS.includes(r?.reason)).length;
+  const sessions = [...bySession.entries()]
+    .map(([key, count]) => {
+      const [id, client] = key.split('|');
+      return { session_id: id, client, count };
+    })
+    .sort((a, b) => b.count - a.count);
   return {
     total,
+    // The log is per-device and shared: two agents on one booted simulator
+    // write one interleaved file. More than one session here means the counts
+    // below are a pool, and CLAUDE.md uses those counts to choose a phase.
+    sessions,
+    session_count: sessions.length,
+    unattributed,
+    // Any unattributed record at all makes this a pool: the whole point is
+    // that they cannot be told apart, and 92 of them is not "one session".
+    pooled: sessions.length > 1 || unattributed > 0,
+    by_flow: Object.fromEntries([...byFlow.entries()].sort((a, b) => b[1] - a[1])),
     by_reason: byReason,
     by_outcome: byOutcome,
     faculty: Object.fromEntries(
@@ -437,7 +532,9 @@ export function breakdown(records) {
       .sort((a, b) => b[1] - a[1])
       .slice(0, 10)
       .map(([fingerprint, count]) => ({ fingerprint, count })),
-    model_turns_spent: records.reduce((acc, r) => acc + (r.model_turns_spent ?? 0), 0),
+    // `kept`, not `records` — a filtered breakdown that reports the whole
+    // log's model turns is the same class of mistake as pooling two sessions.
+    model_turns_spent: kept.reduce((acc, r) => acc + (r.model_turns_spent ?? 0), 0),
   };
 }