simframe 0.9.0 → 0.11.0

package/src/index.js

@@ -5,10 +5,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULTS, STATE_VERSION } from './daemon.js';
 import * as engine from './engine.js';
+import * as regions from './regions.js';
 import { decodePng, encodePng, scaleBitmap } from './png.js';
 import {
   REGION_COLS,
   hexToSignature,
+  isBlackFrame,
+  maxCellDelta,
+  CELL_CHANGE,
   regionDeltas,
   regionMap,
   signatureDiff,
@@ -398,6 +402,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') {
@@ -459,9 +537,31 @@ export async function getFrame(deviceQuery, { detail = 'normal', options } = {})
   let scaledOnRead = false;
   if (maxDim === 0) {
     file = state.fullFile;
-  } else if (maxDim > nativeMax + 8 && fs.existsSync(state.fullFile)) {
+  } else if (maxDim > nativeMax + 8) {
+    // Asking for more detail than the ring frame holds, so it has to come from
+    // a full-resolution frame. The `fs.existsSync(state.fullFile)` this used to
+    // require is exactly the condition that fails routinely — retention thins
+    // full frames aggressively, and `state.fullFile` names one that is often
+    // already gone. When it did, this fell straight through to `latest.png` and
+    // returned a 322x700 image while still calling itself detail "high".
+    //
+    // That was not a small inaccuracy. Every single `sim_look` header in a
+    // two-agent field round read `322x700` on a 402x874pt device, so "high
+    // (1024px, readable small text)" was interpolating a sub-1x source the
+    // whole time. `fullFrameFor` has always known how to find or take a full
+    // frame — state named full/9660.png while the directory held eight frames
+    // at 1206x2622 — and this path simply never asked it.
+    //
+    // What this does *not* explain, though it is tempting: the OCR corruption
+    // in that round's log (`saaiad@example.com`, `suomit order`). OCR has
+    // always gone through `fullFrameFor`, and the daemon's own text recognition
+    // reads the live surface at native resolution, so neither was ever looking
+    // at the small frame. Those errors are a desktop-width page rendering its
+    // labels at a few pixels tall. Fixing what the caller *sees* does not fix
+    // what OCR reads, and saying so here keeps the next reader from assuming it did.
+    const source = await fullFrameFor(device.udid, state);
     const out = path.join(p.dir, `read-${maxDim}.png`);
-    await resize(state.fullFile, out, maxDim);
+    await resize(source, out, maxDim);
     file = out;
     scaledOnRead = true;
   } else if (maxDim < nativeMax - 8) {
@@ -473,17 +573,50 @@ export async function getFrame(deviceQuery, { detail = 'normal', options } = {})
 
   const png = fs.readFileSync(file);
   const bmp = pngSize(png);
+  // The age must describe the *bytes*, not the state that dates them.
+  //
+  // These are two different files. `state.json` is written when a frame is
+  // recorded; the image is a separate write. A freshly started daemon publishes
+  // fresh state while `latest.png` is still the previous session's — which is
+  // when a caller's first look of a session happens. Reported, and it is the
+  // worst failure this tool can have: a header reading `frame #714 · 84ms old ·
+  // still for 17173ms` above an image whose status-bar clock said 6:11 when the
+  // real time was 11:10. `sim_ui` was right in the same session because the
+  // accessibility tree is read live and in-process; only the image comes from a
+  // file, so only the image can be hours stale while the header says otherwise.
+  //
+  // Taking the *larger* of the two ages cannot overstate freshness. It can
+  // overstate staleness by however long the two writes are apart, which is 6ms
+  // measured on a healthy daemon — the right direction to be wrong in.
+  let fileAgeMs = null;
+  try { fileAgeMs = Date.now() - fs.statSync(file).mtimeMs; } catch { /* stat is advisory */ }
+  const stateAgeMs = Date.now() - state.capturedAt;
+  const ageMs = Number.isFinite(fileAgeMs) ? Math.max(stateAgeMs, fileAgeMs) : stateAgeMs;
   return {
     device,
     state,
     png,
     width: bmp.width,
     height: bmp.height,
-    ageMs: Date.now() - state.capturedAt,
+    ageMs,
+    // Said out loud when the image is materially older than the state, because
+    // "this picture is not of the screen the rest of this response describes" is
+    // not something a caller can work out for themselves.
+    frameBehindMs: Number.isFinite(fileAgeMs) && fileAgeMs - stateAgeMs > FRAME_BEHIND_MS
+      ? Math.round(fileAgeMs - stateAgeMs)
+      : null,
     scaledOnRead,
   };
 }
 
+/**
+ * How far the image may lag the state before it is worth saying so.
+ *
+ * Measured on a healthy daemon, the two writes land 6ms apart. A second is far
+ * outside that and far inside the hours-stale case this exists to catch.
+ */
+const FRAME_BEHIND_MS = 1000;
+
 function pngSize(png) {
   return { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
 }
@@ -497,6 +630,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 +705,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 +727,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 +791,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 +815,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.
@@ -890,10 +1124,76 @@ export async function readScreenWith(deviceQuery, { useAx = true, useOcr = true,
   return { device, entry, points: { width: geo.pointWidth, height: geo.pointHeight } };
 }
 
-export async function locate(
+/**
+ * A target that answers the query but sits outside the viewport.
+ *
+ * The off-screen filter above is right — an element in the tree below the fold
+ * is untappable in fact — but "not on this screen" was the wrong way to say so.
+ * Reported: a `waitFor` spent its full 15s timeout and stopped the flow while
+ * the control sat one scroll down. Waiting cannot fix that and scrolling can.
+ */
+export function offScreenMatch(targets, query, points) {
+  // Both axes: a horizontal row puts elements past the right edge, and checking
+  // only `y` reported them as visible.
+  const off = (targets ?? []).filter((t) => t.label && regions.offViewport(t, points));
+  if (!off.length) return null;
+  const hit = matching.resolve(off, query);
+  if (hit.status === 'ok') return hit.target;
+  // Ambiguous off-screen is still an answer to "why is it not here".
+  return hit.status === 'ambiguous' && hit.alternatives?.length ? hit.alternatives[0] : null;
+}
+
+/**
+ * Which sensors a read asks for by default.
+ *
+ * `full` is the default and what CLAUDE.md fixes: accessibility and OCR fused
+ * into one element list. `ax-first` asks for the tree alone — 85 ms against
+ * 142 ms warm — and pays for OCR only when the cheap read could not answer the
+ * question.
+ *
+ * The escalation is the whole point, and it is what makes this safe to try. A
+ * mode that just dropped OCR would lose every OCR-only element, which is
+ * precisely how the map cut lost discovery: nothing became untappable, but the
+ * agent could no longer see what was there. Here a resolve failure — the one
+ * signal that says "the cheap sensor was not enough" — triggers a full read
+ * before anyone is told the target is absent. Wrong guesses cost a second read;
+ * they cannot cost a wrong answer.
+ */
+export function sensorMode(options) {
+  // Per call first, then the environment. The environment is fixed when a
+  // process starts, and an MCP server is one long-lived process — so a tester
+  // asked to compare two sensor modes in one session could not do it, which is
+  // exactly what happened: round 6's A was run and B and C could not be. Their
+  // own suggestion was three server entries with three env blocks, and it is
+  // the worse fix: three servers on one device means three writers, against the
+  // one-writer-per-device rule, and it makes an A/B a configuration change
+  // rather than an argument.
+  const asked = options?.sensor;
+  const raw = String(asked ?? process.env.SIMFRAME_SENSOR ?? '').trim().toLowerCase();
+  return raw === 'ax-first' || raw === 'axfirst' ? 'ax-first' : 'full';
+}
+
+export async function locate(deviceQuery, query, opts = {}) {
+  if (sensorMode(opts.options) !== 'ax-first' || opts.useOcr === false || opts.escalated) {
+    return locateWith(deviceQuery, query, opts);
+  }
+  const options = opts;
+  try {
+    return await locateWith(deviceQuery, query, { ...options, useOcr: false, escalated: true });
+  } catch (err) {
+    // Only a perception failure earns the expensive retry. A refused selector or
+    // an ambiguity between two things the tree *did* see is not going to be
+    // settled by reading more text.
+    const why = metrics.escalationOf(err);
+    if (why?.reason !== 'unknown_screen' && why?.reason !== 'ambiguous_intent') throw err;
+    return locateWith(deviceQuery, query, { ...options, useOcr: true, refresh: true, escalated: true });
+  }
+}
+
+async function locateWith(
   deviceQuery,
   query,
-  { index, refresh = false, useAx = true, useOcr = true, settleMs = MEMORY_SETTLE_MS, options } = {},
+  { index, refresh = false, useAx = true, useOcr = true, settleMs = MEMORY_SETTLE_MS, options, escalated } = {},
 ) {
   const { device, state: firstState } = await ensureDaemon(deviceQuery, options);
   const udid = device.udid;
@@ -916,11 +1216,47 @@ export async function locate(
     // be checked against structural identity without paying for a perception
     // pass — which is the whole reason a ref exists.
     const near = screenmap.recallNearest(udid, firstState.layoutHash);
-    const hit = refs.resolveRef(udid, selector.ref, {
-      layoutHash: firstState.layoutHash,
-      structuralHash: near?.entry?.structuralHash ?? null,
-      screenKnown: Boolean(near),
-    });
+    let hit;
+    try {
+      hit = resolveRefHere();
+    } catch (err) {
+      // A stale ref carries the label it was numbered against, so it need not
+      // cost the rest of the batch. Reported: `#19 was numbered on a different
+      // screen (61b835b7 → 6f34c006)` because dashboard cards finished loading
+      // and shifted the layout — the same screen, a new hash — and that one
+      // refusal aborted the three remaining steps.
+      //
+      // It re-resolves by label rather than by coordinate, and it *says so*.
+      // The number is not honoured; the caller's own words are, which is what
+      // they would have written instead. Resolving the old coordinates would be
+      // the dangerous version of this, and is not what happens.
+      // Only layout drift is recoverable. `identity` means the numbers were
+      // drawn somewhere else, and the label they stood for appearing here is
+      // coincidence rather than evidence — measured: `#1` numbered "Reminders"
+      // in Reminders re-resolved in Contacts onto the status-bar back-to-app
+      // breadcrumb "• Reminders", and reported ok.
+      if (!err.staleRef || !err.staleLabel || err.staleKind !== 'drift') throw err;
+      let again;
+      try {
+        again = await locateWith(deviceQuery, err.staleLabel, {
+          index, refresh: true, useAx, useOcr, settleMs, options, escalated,
+        });
+      } catch (second) {
+        // The number was not honoured and the label it stood for is not here
+        // either. That is still a refusal to tap stale coordinates, but by the
+        // time it surfaces it looks like an ordinary "not on this screen" and a
+        // caller cannot tell the two apart. Carrying the marker across says
+        // which question was actually asked.
+        second.staleRef = true;
+        second.staleLabel = err.staleLabel;
+        throw second;
+      }
+      return {
+        ...again,
+        from: 'ref-relabelled',
+        relabelled: { ref: selector.ref, label: err.staleLabel, why: err.message },
+      };
+    }
     return {
       device,
       state: firstState,
@@ -929,6 +1265,23 @@ export async function locate(
       distance: 0,
       settled: true,
     };
+
+    function resolveRefHere() {
+      return refs.resolveRef(udid, selector.ref, {
+      layoutHash: firstState.layoutHash,
+      structuralHash: near?.entry?.structuralHash ?? null,
+      // How far that recall reached. `recallNearest` is deliberately tolerant —
+      // a list with new rows is still the same screen — so at any distance
+      // above zero it is a *guess* about which screen this is, and a guess must
+      // not be the sole grounds for refusing a ref. Reported from the field: a
+      // refusal reading `#5 was numbered on a different screen
+      // (0f7b9e3e → 48e5c92d)` where both calls' headers printed the identical
+      // screen, because the map named the screen from a tolerant recall while
+      // refs treated that same recall as exact.
+        structuralDistance: near?.distance ?? null,
+        screenKnown: Boolean(near),
+      });
+    }
   }
   if (selector.exact) query = selector.label;
   // Key memory off a settled frame, never off whichever frame happened to be
@@ -985,7 +1338,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, intent: query },
       );
     }
     if (outcome.status === 'ok') {
@@ -999,8 +1356,25 @@ export async function locate(
     // here undoes every guard above — it has no off-screen filter and no
     // coverage weighting, and it is what returned a scrolled-away list row for
     // "back". "Not found" is the correct answer.
-    const visible = entry.targets.filter((t) => t.label && t.y >= 0 && t.y <= points.height);
+    const visible = entry.targets.filter((t) => t.label && !regions.offViewport(t, points));
     const sample = visible.slice(0, 12).map((t) => t.label.slice(0, 24)).join(', ');
+    // "Not on this screen" and "not in view" are different answers, and giving
+    // the first for the second cost a reported 15 seconds: a `waitFor REVIEW`
+    // burned its whole timeout while REVIEW sat one scroll below the fold, and
+    // then stopped the flow. Waiting cannot bring a thing into view, and
+    // scrolling can — so the difference is the whole of what to do next.
+    const offScreen = offScreenMatch(entry.targets, query, points);
+    if (offScreen) {
+      throw metrics.tag(
+        new Error(
+          `"${query}" is in the tree but not in view — it is at y=${Math.round(offScreen.y)}`
+          + ` on a ${Math.round(points.height)}pt screen. Scroll to it (sim_scroll_to) rather than waiting;`
+          + ' waiting cannot bring it into view.',
+        ),
+        from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
+        { candidates: visible.slice(0, 8), intent: query },
+      );
+    }
     // Which escalation this is depends on whether the screen was recognised.
     // Screen memory had nothing for it (`from` is one of the built values) and
     // the target is missing: that is not knowing the screen. On a screen
@@ -1008,7 +1382,7 @@ export async function locate(
     throw metrics.tag(
       new Error(`"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`),
       from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
-      { candidates: visible.slice(0, 8) },
+      { candidates: visible.slice(0, 8), intent: query },
     );
   }
 
@@ -1020,7 +1394,7 @@ export async function locate(
     throw metrics.tag(
       new Error(`"${query}" is not on this screen. Visible: ${sample || '(nothing readable)'}`),
       from === 'memory' ? 'ambiguous_intent' : 'unknown_screen',
-      { candidates: visible.slice(0, 8) },
+      { candidates: visible.slice(0, 8), intent: query },
     );
   }
   return { device, state: current, entry, target, from, distance, settled, screens: screenmap.stats(udid).screens };
@@ -1039,6 +1413,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.
  *
@@ -1101,6 +1507,11 @@ export async function screenIdentity(deviceQuery, { options, confirmNovel = true
       keyboard: Boolean(entry.keyboard),
       layoutHash: current.layoutHash,
       settled,
+      // Settled and incomplete are different states and used to render
+      // identically. A screen awaiting a network call is perfectly still; a
+      // person sees a spinner and knows to wait. The classifier already says
+      // so, and nothing above this line was asking.
+      loading: current.transition?.kind === 'loading',
       // Carried out so callers that want the elements as well as the identity
       // do not pay for a second perception pass to get them. The compact
       // screen map needs both, and reading twice was the whole cost of it.
@@ -1122,7 +1533,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