simframe 0.15.1 → 0.17.0

package/README.md

@@ -172,6 +172,18 @@ selector that did not *resolve* and nothing else, because retrying from a screen
 you did not expect to be on is a second guess. A destructive-looking label is
 refused as a substitute even if you list it.
 
+**Steps that may legitimately have nothing to act on.** `{"tap": "Not Now",
+"optional": true}` is skipped when nothing matches and runs normally when
+something does. It exists because the opposite cost real time: a batch that
+included a dismissal for a first-launch sheet lost **six correct steps** on the
+next run because the sheet *did not appear*. A nag screen, a permission prompt,
+a "What's New" or a cold-start splash otherwise makes a flow unbatchable, which
+is the expensive outcome — a call per step instead of a call per flow. Only a
+selector that resolved to **nothing** is absorbed: a target that is on screen
+twice is ambiguous, not absent, and must still verify. Skipped steps are
+reported, because "the sheet was gone" and "the sheet was dismissed" are
+different facts.
+
 **`{"seek": "change username", "budget": 6}`** opens containers, checks, and
 comes back, depth first, inside a hard budget. It **acts** — opening a door
 changes state — and it refuses to open anything that commits, abandons or
@@ -400,7 +412,7 @@ steer the model is a tool surface the model uses wrong.
 | `sim_do` | **The main tool.** A whole flow in one call — tap, type, scroll, wait, assert — each step settling before the next and verified against what it did last time. |
 | `sim_state` | The cheapest question there is: has anything changed **since your last look**, and which regions moved. |
 | `sim_goto` | Walk to a screen simframe has been to before, planning the route through remembered transitions. |
-| `sim_flow_run` | Replay a flow that verified end to end. |
+| `sim_flow_run` | Replay a saved flow — **zero model calls**, which is the only path to human wall clock. A first traversal saves as *provisional*; one replay in which every step passed confirms it. A run with a contradicted step, a failed step, or one that never reached its last step is refused and says which. |
 | `sim_find` | Resolve an intent to one control, without acting on it. |
 | `sim_tap` · `sim_type_into` · `sim_scroll_to` · `sim_wait_for` · `sim_assert` | Single actions, for when you genuinely only have one step. Each is one `sim_do` step underneath. |
 | `sim_launch` · `sim_open_url` · `sim_permission` | Launch with arguments and environment; open a deep link; grant a privacy permission instead of tapping a system alert. A launch is **confirmed to have reached the front**, by comparing the pid `simctl` started against the pid the device reports as frontmost — so *"the process started"* is no longer reported as *"the app is on screen"*. |
@@ -701,6 +713,55 @@ Reproduce all of it with `npm run bench`, which prints the same table against
 your machine. Full detail, including the measurement traps, is in
 [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md).
 
+### Wall clock per step — where the time really goes
+
+Every number above is microscopic next to the one that decides how fast this
+feels, and it took two field reports to see it. Per-step wall clock is
+
+```
+(model round trip + simframe work × n) / n        for n steps in one call
+```
+
+**Compare like with like, which this table used not to.** A human tester's
+1.95 s per step is the *whole* loop — look at the screen, decide what to do,
+do it. Any row that does not include a decision is not comparable to it.
+
+| | perceives | decides | acts | per step |
+| --- | --- | --- | --- | --- |
+| **a human tester, measured** | yes | yes | yes | **1.95 s** |
+| **simframe, batch of 2 — the recorded median** | yes | yes | yes | **~11.7 s** |
+| simframe, batch of 4 | yes | yes | yes | ~6.7 s |
+| simframe, one model call per step | yes | yes | yes | ~21.7 s |
+| — simframe's mechanical half alone | yes | **no** | yes | ~1.7 s |
+| — a saved flow replayed | yes | **no** | yes | 1.98 s |
+
+**The only like-for-like comparison is 1.95 s against ~11.7 s: about six times
+a human**, and about eleven times when a failure forces one model call per step.
+
+The two indented rows are the ones this README used to lead with, and both are
+category errors when set against 1.95 s. The 1.7 s is simframe with the thinking
+taken out — the thinking is the model round trip, which is most of the clock.
+And a replay *decides nothing*: it is a recording being played back, so its fair
+counterpart is a human repeating a flow they have memorised, who would be well
+under 1.95 s. Replay against a human working something out for the first time is
+a rehearsal measured against a first attempt.
+
+What the two rows do establish, and it is the finding that reordered this
+project: **there is nothing left to win inside the engine.** 1.7 s is small
+beside a 20 s round trip, so making perception or input faster buys single-digit
+percentages. The only variable that matters is `n` — how many steps one decision
+covers. Every improvement here has come from raising it, not from faster code.
+A field report put the split at **34% simframe, 60% agent round trips** over
+462 s of wall clock — the tester's *"30+ seconds between each step"* was
+accurate and was not simframe. So there is nothing left to win inside the
+engine, and the only variable is `n`: `simframe hpi` reports `steps_per_call`
+for exactly that reason.
+
+Which is why **every hard-fail that drops a caller back to single-stepping is a
+latency bug**. Between two field reports on the same flow, one run took 33 tool
+calls and the next took **16**, for 28 executed steps and no screenshots at
+all — the difference being defects fixed, not code made faster.
+
 ## How it works
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/bench-hpi.mjs

@@ -243,8 +243,11 @@ const base = committed.overall ?? {};
 const failures = metrics.gateAgainst(committed, report);
 
 console.log(`\ngate vs ${path.relative(ROOT, baselineFile)} (measured ${committed.measured_at ?? '?'})`);
-console.log(`  HPI_accuracy ${base.hpi_accuracy ?? '—'} -> ${o.hpi_accuracy ?? '—'}`);
-console.log(`  HPI_time     ${metrics.gateTime(base) ?? '—'} -> ${metrics.gateTime(o) ?? '—'}`);
-console.log(`  band         ${metrics.TIME_REGRESSION * 100}% (median of ${passTimes.length || 1} pass(es))`);
+console.log(`  HPI_accuracy ${base.hpi_accuracy ?? '—'} -> ${o.hpi_accuracy ?? '—'}   (any drop fails)`);
+console.log(`  step_ratio   ${o.step_ratio ?? '—'}   (fails above ${metrics.STEP_RATIO_CEILING})`);
+// Printed apart from the two that gate, and labelled, because a number in a
+// gate block gets read as a threshold whether or not it is one.
+console.log(`  ${metrics.timeTrend(committed, report)}`);
+console.log(`               median of ${passTimes.length || 1} pass(es), on this host`);
 for (const f of failures) console.log(`FAIL ${f}`);
 process.exit(failures.length ? 1 : 0);

package/scripts/ci-memory.mjs

@@ -635,19 +635,44 @@ check(walked.ok === true || outcomes.includes(walked.reason),
   walked.ok ? (walked.already ? 'already there' : `walked ${walked.ranSteps} step(s)`) : walked.reason);
 
 console.log('\n--- what may be saved, and what may not ---');
-// A flow with an unverified step in it is a recording of something that may not
-// have worked, and replaying it faithfully reproduces the doubt. So the
-// contract runs both ways and both directions are checked against whatever the
-// run actually produced, rather than assuming it verified.
+// **A first traversal must be recordable**, which is the opposite of what this
+// check used to assert. The old contract refused any flow with a non-`ok`
+// verdict — and a first traversal is all-`unverified` by construction, since
+// there is no prior observation to compare against. So no flow could ever be
+// recorded, replay was unreachable, and the only zero-model-call path in the
+// tool was sealed shut behind a gate nobody could pass.
+//
+// The refusal now needs evidence *against* a step rather than the absence of
+// evidence for it. Checked against whatever the run actually produced rather
+// than assuming a shape, as before.
 const attempt = await jsonRetry(['do', LOOP, `--save=${FLOW_NAME}`], { allowFail: true });
+//
+// Three outcomes, not two. The missing one is a step that ran and *failed*: a
+// failing step stops the batch, so a failure on the last step leaves
+// `ranSteps === steps.length` and the run reads as complete. A peer watched
+// `FLOW FAILED — 4 ok, 1 failed (of 5)` save itself. This branch is also the
+// one that goes stale: yesterday the save contract was replaced, the unit test
+// was updated, and this file was left asserting the old rule — so the three
+// cases are enumerated here explicitly rather than left as an `else`.
+const contradicted = attempt.results.some((r) => /^unexpected/.test(r.verification?.verdict ?? ''));
+const anyFailed = attempt.results.some((r) => !r.ok);
 const clean = attempt.results.every((r) => !r.verification || r.verification.verdict === 'ok');
-if (clean) {
-  check(attempt.saved?.ok === true, 'a flow whose every step verified is saved',
-    `${attempt.saved?.steps} steps`);
-} else {
-  check(attempt.saved?.ok === false && attempt.saved?.reason === 'unverified-steps',
-    'a flow with an unverified step is refused, not quietly saved',
+if (contradicted) {
+  check(attempt.saved?.ok === false && attempt.saved?.reason === 'contradicted-steps',
+    'a flow with a contradicted step is refused, not quietly saved',
     `${attempt.saved?.reason} (${(attempt.saved?.verdicts ?? []).join(', ')})`);
+} else if (anyFailed) {
+  check(attempt.saved?.ok === false && attempt.saved?.reason === 'failed-steps',
+    'a flow with a step that ran and failed is refused, not quietly saved',
+    `${attempt.saved?.reason} (failed step ${(attempt.saved?.failed ?? []).join(', ')})`);
+} else {
+  check(attempt.saved?.ok === true, 'a first traversal is recordable',
+    `${attempt.saved?.steps} steps`);
+  check(attempt.saved?.provisional === !clean,
+    clean
+      ? 'and a flow whose every step verified is confirmed outright'
+      : 'and it is marked provisional, because nothing had been seen before to compare against',
+    `provisional=${attempt.saved?.provisional}`);
 }
 
 // --force is the deliberate override, and it is what lets the replay machinery
@@ -660,6 +685,26 @@ if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.sa
   check(replayed.ranSteps >= 1 && Array.isArray(replayed.results),
     'and replays from disk with no model in the loop',
     `${replayed.ranSteps}/${replayed.totalSteps} steps`);
+  // The other half of the bootstrap, and the reason "provisional" is not a
+  // state nothing ever leaves: a clean replay is the confirmation a first
+  // traversal could not give. Only asserted when the replay actually ran to
+  // the end — a partial replay promotes nothing, deliberately.
+  const after = await jsonRetry(['flow', 'list']);
+  const entry = after.find((f) => f.name === FLOW_NAME);
+  if (replayed.ok) {
+    check(entry && !entry.provisional,
+      'and a clean replay confirms a provisional flow',
+      `provisional=${entry?.provisional ?? 'gone'}`);
+  } else {
+    // The other direction, and it is the one that was silently wrong: promotion
+    // keyed on `ranSteps === steps.length`, which a failure on the *last* step
+    // satisfies. Both of a peer's saved flows were marked confirmed by replays
+    // that failed. A confirmation that a failing replay can grant is not a
+    // confirmation, so the negative case has to be checked too.
+    check(entry?.provisional === true,
+      'and a replay that failed does NOT confirm the flow it just disproved',
+      `ok=${replayed.ok}, provisional=${entry?.provisional}`);
+  }
   const unknown = await cli(['flow', 'run', 'no-such-flow'], { expectFail: true });
   check(/no flow/i.test(unknown), 'an unknown flow name is refused with what is known');
 }

package/src/actions.js

@@ -19,6 +19,29 @@ import { launchApp, openUrl, setPermission, terminateApp } from './platform/inde
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const MAX_PAUSE_MS = 5000;
+/**
+ * Above this many characters a fill uses the pasteboard; at or below it, the
+ * keyboard.
+ *
+ * The pasteboard is the right default for long text and was the default for
+ * *all* text in `sweep`, which a field report showed costing far more than it
+ * saved. iOS 26 raises a system consent alert — *"… would like to paste from
+ * CoreSimulatorBridge"* — on the first paste into an app, and it fired on a
+ * **nine-character** value. The alert covered the form, collapsed the
+ * accessibility tree to OCR-only, and failed the batch; the recovery chain that
+ * followed was close to half of that session's wasted model round trips.
+ *
+ * `sim_type_into` already defaults to the keyboard. Only `sweep`'s fill did
+ * not, so the reporter got the pasteboard without asking for it.
+ *
+ * Why a threshold is safe rather than a trade against exactness — the reason
+ * pasteboard-by-default was chosen: `type` with `into` reads the field back,
+ * and retries once locally if nothing landed. So a keystroke path that a
+ * keyboard layout mangles is *caught*, not silently accepted. 40 characters is
+ * the reporter's own suggestion and covers names, emails and short
+ * descriptions, while a paragraph still goes by pasteboard where it belongs.
+ */
+const KEYBOARD_UP_TO = 40;
 /**
  * A tapped field is typed into once the screen has settled, not after a fixed
  * wait.
@@ -323,6 +346,16 @@ export async function runScript(
   // the caller returns to Claude is rendered from this, so describing the end
   // state costs nothing beyond the verification pass the flow already ran.
   let endScreen = null;
+  // Where this run began, so a flow saved from it can say what it assumes.
+  //
+  // Null when the first step does not depend on where we were — see
+  // `resetsTheScreen`.
+  //
+  // It was recorded as `null` on every flow 0.16.0 saved, which a peer caught:
+  // "replay never checks it is starting where it was recorded". Reading it is
+  // free — the first step computes the identity anyway — and it is a fact the
+  // recording had and discarded.
+  let startScreen = null;
   // At most one recovery per run. Pressing home while already on the springboard
   // moves nothing and is not a failure, so an unbounded retry would rebuild the
   // session and press again on every such step for no reason.
@@ -370,6 +403,9 @@ export async function runScript(
       ? (carriedScreen ?? await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs, confirmNovel }))
       : null;
     carriedScreen = null;
+    if (i === 0 && !resetsTheScreen(step)) {
+      startScreen = beforeScreen ? { hash: beforeScreen.hash ?? null, tokens: beforeScreen.tokens ?? null } : null;
+    }
     // What this action did last time it was taken here, if ever.
     const prediction = verify && beforeScreen?.hash ? graph.predict(udid, beforeScreen, step) : null;
     try {
@@ -922,6 +958,33 @@ export async function runScript(
         break;
       }
     } catch (err) {
+      // A step that was allowed not to be there, and is not there.
+      //
+      // `or:` supplies alternative *selectors*; nothing could express "skip
+      // this if absent". So a batch crossing a first-launch nag, a permission
+      // prompt or a "What's New" could not be batched at all — the interstitial
+      // appears on run one and not on run two, the step fails, and every
+      // remaining step is discarded. A peer lost six correct steps because a
+      // sheet *did not* appear, and on the framing that every hard-fail
+      // dropping a caller back to single-stepping is a latency bug, that is the
+      // most expensive shape there is: ~20 s per step, for the rest of the plan.
+      //
+      // Deliberately narrow. Only `unknown_screen` — the selector resolved to
+      // nothing — absorbs. `ambiguous_intent` means the target *is* there,
+      // twice, and a step that is present must still verify; so must one that
+      // resolved and then failed. "Skip if absent" must not become "tap
+      // whatever is there".
+      if (step.optional && didNotResolve(err)) {
+        results.push({
+          index: i,
+          action: step.action,
+          ok: true,
+          skipped: true,
+          ms: Date.now() - stepStart,
+          detail: `skipped — optional, and ${JSON.stringify(String(goalOf(step) ?? step.action))} is not on this screen`,
+        });
+        continue;
+      }
       results.push({ index: i, action: step.action, ok: false, ms: Date.now() - stepStart, error: err.message });
       const why = metrics.reasonForStepError(step, err);
       noteEscalation({
@@ -997,6 +1060,7 @@ export async function runScript(
     // navigate.saveFlow without the caller reassembling what it just ran.
     steps,
     flowId,
+    startScreen,
     endScreen,
     results,
     ok: !failed,
@@ -1439,6 +1503,53 @@ export function alternativesFor(step) {
   return list.map((v) => (typeof v === 'string' ? v : v?.value ?? v?.target ?? v?.label)).filter(Boolean);
 }
 
+/**
+ * Does this step make the screen we were on irrelevant?
+ *
+ * A flow that opens with `launch`, a deep link, or the home button does not
+ * assume anything about where it starts — it goes and puts the device
+ * somewhere. Recording a start screen for such a flow records where the device
+ * happened to be beforehand, which is noise, and then reports a mismatch on
+ * every replay that began anywhere else.
+ *
+ * Measured, not reasoned: a flow opening with `launch --relaunch` replayed
+ * perfectly and still printed "recorded starting on 8292b488, replayed from
+ * 39351dab", because the recording had followed a run that ended on Settings
+ * root and the replay followed one that ended on About. Most flows open with a
+ * launch, so that note would have fired on most correct replays — which is
+ * item 175's defect exactly, in a feature added the same day 175 was written up.
+ */
+export function resetsTheScreen(step = {}) {
+  if (step.action === 'launch' || step.action === 'openUrl') return true;
+  return step.action === 'button' && /^home$/i.test(String(step.value ?? '').trim());
+}
+
+/**
+ * Did this failure mean "the thing is not here", as opposed to any other way a
+ * step can fail? The one question `optional` is allowed to ask.
+ *
+ * **Not `reason === 'unknown_screen'`, which is what this said for one build and
+ * what made `optional` a no-op on every screen it was built for.** The tag at
+ * the throw site is chosen by whether the *screen* was recognised, not by
+ * whether the *target* was found: on a screen recalled from memory an absent
+ * target is tagged `ambiguous_intent` too. So a conditional interstitial on a
+ * well-known screen — the whole use case — never absorbed. Caught by running it
+ * against a device; the unit test exercised this predicate and passed, because
+ * it tested the predicate rather than the path.
+ *
+ * The distinction that actually exists is `ambiguous`, set only where something
+ * was found *several times over*, and the comment at that throw site had
+ * already written down why it matters: "more time cannot make a thing unique,
+ * and it can make an absent thing arrive." Absent is the case `optional` may
+ * skip; present-twice must still verify.
+ */
+const RESOLVE_REASONS = new Set(['unknown_screen', 'ambiguous_intent']);
+
+export function didNotResolve(err) {
+  const tagged = metrics.escalationOf(err);
+  return Boolean(tagged && RESOLVE_REASONS.has(tagged.reason) && !tagged.ambiguous);
+}
+
 export function mayRetryAfter(err) {
   const tagged = metrics.escalationOf(err);
   return Boolean(tagged && RESOLVE_FAILURES.has(tagged.reason));
@@ -1559,12 +1670,35 @@ async function stillOnPlan(deviceQuery, verification, nextStep, options) {
   // neither is evidence about where we are.
   if (!target || /^#\d+$/.test(String(target).trim()) || /^@?-?\d+\s*,\s*-?\d+$/.test(String(target).trim())) return false;
   if (!ACTION_STEPS.has(nextStep.action) && nextStep.action !== 'assert' && nextStep.action !== 'waitFor') return false;
-  try {
-    const hit = await api.locate(deviceQuery, String(target), { options });
-    return Boolean(hit?.target);
-  } catch {
-    return false;
+  // **Settle before looking, and look twice.**
+  //
+  // This asked once, immediately, and the circumstance it is asked in is
+  // precisely a screen that is still arriving: a content-driven screen whose
+  // rows have not rendered hashes differently from the one memory expected —
+  // which is what produced the `unexpected-screen` — *and* does not yet hold
+  // the next step's target. So the one signal that could have rescued the batch
+  // was read at the only moment it was guaranteed to be absent, and a correct
+  // navigation aborted the run.
+  //
+  // Measured cost of getting this wrong: a field report lost a 7-step plan at
+  // step 5 on a tap that had correctly advanced a wizard, and every discarded
+  // step is ~20s of model latency to re-plan. A settle here costs under a
+  // second and is paid only on the failure path.
+  //
+  // It cannot manufacture a continue: the next step's own target still has to
+  // resolve, which is strong evidence about where we are.
+  for (let look = 0; look < 2; look += 1) {
+    await api.waitFor(deviceQuery, {
+      mode: 'settle', stableMs: 300, timeoutMs: look === 0 ? 1200 : 800, options,
+    }).catch(() => null);
+    try {
+      const hit = await api.locate(deviceQuery, String(target), { refresh: true, options });
+      if (hit?.target) return true;
+    } catch {
+      /* not here yet; one more look, then the halt stands */
+    }
   }
+  return false;
 }
 
 /**
@@ -2153,6 +2287,36 @@ export const SWEEP_SECTIONS = 10;
 
 const sweepKey = (r) => `${alnum(r.label)}\u0000${Math.round((r.x ?? 0) / 8)}`;
 
+/**
+ * Every name a caller may legitimately write for a swept row.
+ *
+ * `sweep` matched on `r.label` alone, and in React Native most interactive
+ * controls have a `testID` and no accessibility label — so a field `sweep`
+ * itself had just printed came back as **"NOT FOUND anywhere"**:
+ *
+ *   swept 3 section(s) ... 29 distinct element(s);
+ *   NOT FOUND anywhere: "create-service-request-3-requested-by-input"
+ *   ...
+ *   #18 field  201,480  create-service-request-3-requested-by-input
+ *
+ * Four lines apart, in one response. The next call filled it by `#18` first
+ * try. The reporter called it the most confidence-damaging failure of the run,
+ * because "NOT FOUND anywhere" is a strong claim and it briefly convinced them
+ * the form did not have the field they were looking at.
+ *
+ * **The third time this same assumption has been reported.** Item 152 was the
+ * identifier missing from `matching.rank`; `ee305d4` was a label the matcher
+ * refused; this is `sweep` carrying its own ad-hoc matcher that never learned
+ * either fix. A resolver per call site is a resolver that has to be corrected
+ * per call site — the names belong in one place, which is what this is.
+ */
+const sweepNames = (r) => [r.label, r.identifier, ...(r.aliases ?? [])].filter(Boolean).map(alnum);
+/** Does this row answer to `needle` by any of its names? */
+const sweepHolds = (r, needle) => {
+  const want = alnum(needle);
+  return want ? sweepNames(r).some((n) => n.includes(want)) : false;
+};
+
 async function sectionHere(deviceQuery, options) {
   try {
     const map = await view.screenMap(deviceQuery, { options, refresh: true });
@@ -2298,12 +2462,29 @@ async function sweep(deviceQuery, udid, step, ctx) {
     // scroll back to it.
     if (fill) {
       for (const [label, text] of Object.entries(fill)) {
-        if (!here.some((r) => alnum(r.label).includes(alnum(label)))) continue;
+        if (!here.some((r) => sweepHolds(r, label))) continue;
         try {
-          await runStep(deviceQuery, udid, {
-            action: step.paste === false ? 'type' : 'paste', into: label, text: String(text),
+          // **Keep what the step said.** `paste` and `type` both read the field
+          // back and say so — "unconfirmed", "reads empty", the quiet-field
+          // caveat — and this threw all of it away and printed a bare
+          // `filled "X"`. A field report called that out as the worst failure
+          // mode an automation tool has: a silent no-op reported as a confirmed
+          // action, caught only because the tester took a screenshot on a
+          // hunch. The honesty existed one function down and stopped here.
+          const body = String(text);
+          // Explicit wins; otherwise length decides. See KEYBOARD_UP_TO.
+          const viaPaste = step.paste === true
+            || (step.paste !== false && body.length > KEYBOARD_UP_TO);
+          const said = await runStep(deviceQuery, udid, {
+            action: viaPaste ? 'paste' : 'type', into: label, text: body,
           }, ctx);
-          filled.push(`${JSON.stringify(label)} in section ${section + 1}`);
+          // Anything the step qualified travels with the claim. A step that
+          // confirmed the read-back says nothing extra, so a clean fill still
+          // reads cleanly.
+          const caveat = /unconfirmed|NOT CONFIRMED|reads empty|did not land|nothing was read back/i.test(said ?? '')
+            ? ` — ${String(said).replace(/^(pasted|typed)[^[]*/i, '').trim() || said}`
+            : '';
+          filled.push(`${JSON.stringify(label)} in section ${section + 1}${caveat}`);
         } catch (err) {
           filled.push(`${JSON.stringify(label)} FAILED in section ${section + 1}: ${err.message.split('\n')[0].slice(0, 90)}`);
         }
@@ -2311,7 +2492,7 @@ async function sweep(deviceQuery, udid, step, ctx) {
       }
     }
 
-    if (wanted && [...seen.values()].some((r) => alnum(r.label).includes(alnum(wanted)))) break;
+    if (wanted && [...seen.values()].some((r) => sweepHolds(r, wanted))) break;
     if (fill && !Object.keys(fill).length) break;
     prev = here;
     await scrollOne(deviceQuery, udid, 'down', ctx);
@@ -2319,7 +2500,7 @@ async function sweep(deviceQuery, udid, step, ctx) {
 
   const all = [...seen.values()];
   ctx.sweep = all;
-  const hits = wanted ? all.filter((r) => alnum(r.label).includes(alnum(wanted))) : [];
+  const hits = wanted ? all.filter((r) => sweepHolds(r, wanted)) : [];
   const listed = (wanted ? hits : all).slice(0, 30)
     .map((r) => `[${r.section}] ${JSON.stringify(String(r.label).slice(0, 36))} @${r.x},${r.y}`);
   const unfilled = fill ? Object.keys(fill) : [];
@@ -2334,6 +2515,31 @@ async function sweep(deviceQuery, udid, step, ctx) {
     + (listed.length ? `: ${listed.join(', ')}` : '');
 }
 
+/**
+ * A `waitFor` is satisfied, but the screen is still arriving — hold or go?
+ *
+ * The largest single loss in the 0.15.1 field report: `waitFor "Records"` was
+ * satisfied by a count header reading `78 Records`, the next `tap` fired before
+ * any row had rendered, and the batch aborted with **13 steps unattempted**.
+ * The reporter had even warned us in their own `supervise` text that lists
+ * there render a count header before rows — and the supervisor never got asked,
+ * because from `waitFor`'s point of view the wait had succeeded.
+ *
+ * `stillFillingIn` already recognises exactly this ("a header promises 78
+ * records and only 2 rows are here yet"), and it was wired only to a note on a
+ * step result — advice for the model, costing a round trip to act on. Holding
+ * locally costs milliseconds.
+ *
+ * **It can only ever delay, never fail.** When the budget runs out the wait
+ * still succeeds, carrying what it saw. A `waitFor` that turned a present
+ * target into an error would be the false negative this release just fixed
+ * elsewhere, and a worse trade than the race it is guarding.
+ */
+function holdForContent(found, limit) {
+  if (Date.now() >= limit) return null;
+  return stillFillingIn(found?.entry) ?? null;
+}
+
 async function runStep(deviceQuery, udid, step, ctx) {
   switch (step.action) {
     case 'tap': {
@@ -2778,8 +2984,12 @@ async function runStep(deviceQuery, udid, step, ctx) {
           for (const one of alternatives) {
             try {
               const found = await api.locate(deviceQuery, one, { refresh: step.refresh !== false, options: ctx.options });
+              const arriving = holdForContent(found, limit);
+              if (arriving) { lastError = arriving; continue; }
+              const late = stillFillingIn(found?.entry);
               return `${JSON.stringify(one)} appeared at ${found.target.x},${found.target.y}`
-                + ` (first of ${alternatives.length} awaited)`;
+                + ` (first of ${alternatives.length} awaited)`
+                + (late ? ` [but ${late} — waited out the timeout]` : '');
             } catch (err) {
               lastError = err.message;
             }
@@ -2819,7 +3029,17 @@ async function runStep(deviceQuery, udid, step, ctx) {
           // is the price, and it is the same trade: a read is cheaper than the
           // round trip a wrong verdict causes.
           const found = await api.locate(deviceQuery, query, { index: step.index, refresh: step.refresh !== false, options: ctx.options });
-          return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`;
+          const arriving = holdForContent(found, limit);
+          if (arriving) {
+            // Still coming. Sleep a beat and look again — the loop re-resolves
+            // fresh, so this cannot lock onto a stale reading.
+            await api.waitFor(deviceQuery, { mode: 'stable', stableMs: 200, timeoutMs: 700, options: ctx.options })
+              .catch(() => null);
+            continue;
+          }
+          const late = stillFillingIn(found?.entry);
+          return `"${found.target.label}" appeared at ${found.target.x},${found.target.y}`
+            + (late ? ` [but ${late} — waited out the timeout; the screen may still be arriving]` : '');
         } catch (err) {
           lastError = err.message;
           // Waiting cannot make a thing unique.
@@ -3114,13 +3334,23 @@ export function settleEvidence(w) {
  */
 export function flowSummary(res, { withTime = true } = {}) {
   const time = withTime && Number.isFinite(res.totalMs) ? ` in ${res.totalMs}ms` : '';
-  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}`;
+  // A step that was allowed not to be there and was not there did not run, and
+  // saying so is the difference between "the nag screen was gone" and "the nag
+  // screen was dismissed". Same lesson as the denominator above: a count that
+  // quietly means two things is the defect.
+  const skipped = (res.results ?? []).filter((r) => r.skipped).length;
+  // After the time, in parentheses. Written inline before it, this read
+  // "skipped as absent in 3412ms" — which says the skipping took 3.4 seconds.
+  const skips = skipped
+    ? ` (${skipped} optional step${skipped === 1 ? '' : 's'} skipped as absent)`
+    : '';
+  if (res.ok) return `flow completed — ${res.ranSteps}/${res.totalSteps} steps${time}${skips}`;
   const failed = (res.results ?? []).filter((r) => r.ok === false).length || 1;
   const worked = Math.max(0, res.ranSteps - failed);
   const unattempted = Math.max(0, res.totalSteps - res.ranSteps);
   return `FLOW FAILED — ${worked} ok, ${failed} failed`
     + (unattempted ? `, ${unattempted} not attempted` : '')
-    + ` (of ${res.totalSteps})${time}`;
+    + ` (of ${res.totalSteps})${time}${skips}`;
 }
 
 /**

package/src/cli.js

@@ -285,6 +285,20 @@ async function main() {
   // is a different machine and should say so rather than be guessed at.
   if (flags.readyTimeoutMs) options.readyTimeoutMs = num(flags.readyTimeoutMs);
 
+  // `--help` on any command, not only as the command.
+  //
+  // `simframe hpi --help` did the two worst things in sequence: without
+  // `--device` it demanded a device *before* printing help, and with one it
+  // ignored `--help` and ran the report. A flag that is ignored is worse than
+  // one that is rejected — it silently does something other than what was
+  // asked. (The general case, unrecognised flags being dropped everywhere
+  // rather than here, is filed separately; this is the one that was measured
+  // costing a round trip.)
+  if (flags.help || flags.h) {
+    process.stdout.write(USAGE);
+    return;
+  }
+
   switch (command) {
     case undefined:
     case '-h':
@@ -977,6 +991,9 @@ async function main() {
           return;
         }
         emit(flags, res, [
+          ...(res.startedElsewhere
+            ? [`NOTE: recorded starting on ${res.startedElsewhere.recorded}, replayed from ${res.startedElsewhere.here}`]
+            : []),
           ...(res.results ?? []).map(stepLine),
           actions.flowSummary(res, { withTime: false }),
         ]);
@@ -1242,6 +1259,14 @@ async function main() {
           ? `HPI_time and HPI need a human baseline — none of ${report.overall.flows_measured} measured flow(s) has one yet.`
           : `HPI_time ${report.overall.hpi_time} (harmonic mean over ${report.overall.flows_with_human_baseline} flow(s)), HPI ${report.overall.hpi}`,
         `step_ratio ${report.overall.step_ratio ?? '—'} (target ≤1.5), model turns per flow ${report.overall.model_turns_median ?? '—'}`,
+        // Printed with what it costs, because the number alone means nothing
+        // to a reader and the whole point is that it is the dominant term in
+        // wall clock — far larger than anything inside simframe.
+        `steps per model call ${report.overall.steps_per_call ?? '—'}`
+          + (report.overall.steps_per_call
+            ? ` — about ${(((20000 + 1700 * report.overall.steps_per_call) / report.overall.steps_per_call) / 1000).toFixed(1)}s`
+              + ' per step end to end, of which simframe is ~1.7s. Raise this, not the engine.'
+            : ''),
         flags.out ? `wrote ${flags.out}` : null,
       ]);
       return;

package/src/graph.js

@@ -869,7 +869,7 @@ export const VERDICTS = ['ok', 'no-visible-change', 'unexpected-screen', 'unveri
  * that already exists do its job. A string still works and still means "exact
  * match only", which is right for a stored prediction that has no tokens.
  */
-function sameScreen(udid, a, b) {
+export function sameScreen(udid, a, b) {
   const hashOf = (v) => (typeof v === 'string' ? v : v?.hash);
   const ha = hashOf(a);
   const hb = hashOf(b);

package/src/matching.js

@@ -220,7 +220,49 @@ export function rank(targets, intent, { screen } = {}) {
     // them disappears into the ceiling.
     scored.push({ target: t, score, reasons });
   }
-  return scored.sort((a, b) => b.score - a.score);
+  scored.sort((a, b) => b.score - a.score);
+
+  // **A distinctive fragment of one long name, when nothing else came close.**
+  //
+  // Reported from the field: a `waitFor` on a seven-digit record number gave up
+  // after 20 s on a screen whose own "Visible:" list printed that number inside
+  // a heading — `Record #<digits>`, seventeen characters. The reporter's
+  // guess was that `#` was being treated as significant, or that the matcher
+  // was anchored. It is neither — the number scores **0.287** against the 0.45
+  // floor, because the substring branch in `nameScore` scales by how much of
+  // the name the query covers, and seven digits are 41% of that label.
+  //
+  // That scaling is right and stays: it is what stops "back" beating a real
+  // back button from inside a long list row. But its purpose is to resolve
+  // *competition*, and when there is no competition it is charging a penalty
+  // for a risk that does not exist. So the promotion fires only when **nothing
+  // reached the floor** and **exactly one element** contains the query. The
+  // "back" case is untouched, because a screen with a back button has at least
+  // two names containing "back" and this never runs.
+  //
+  // The score lands just above the floor, not at 1: it is an act of
+  // desperation, not a confident match, and the reason says so — so an
+  // ambiguity check downstream still has something honest to weigh.
+  if (!scored.some((c) => c.score >= MINIMUM_SCORE)) {
+    const q = norm(bare) || norm(intent);
+    const holds = (t) => [t.label, t.identifier, ...(t.aliases ?? [])]
+      .filter(Boolean)
+      .some((n) => norm(n).includes(q) && norm(n) !== q);
+    const only = q.length >= 3 ? visible.filter(holds) : [];
+    if (only.length === 1) {
+      const t = only[0];
+      const existing = scored.find((c) => c.target === t);
+      const reason = `the only element on this screen containing "${intent}"`;
+      if (existing) {
+        existing.score = MINIMUM_SCORE + 0.01;
+        existing.reasons.push(reason);
+      } else {
+        scored.push({ target: t, score: MINIMUM_SCORE + 0.01, reasons: [reason] });
+      }
+      scored.sort((a, b) => b.score - a.score);
+    }
+  }
+  return scored;
 }
 
 /** How close two candidates may be before the answer counts as ambiguous. */

package/src/mcp.js

@@ -13,6 +13,7 @@ import { REGION_COLS, REGION_ROWS, regionMap } from './analyze.js';
 import * as actions from './actions.js';
 import * as api from './index.js';
 import * as input from './input.js';
+import * as supervisor from './supervisor.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
 import { bootedDevices, listDevices, permissionServices, resolveDevice } from './platform/index.js';
@@ -133,7 +134,7 @@ const TOOLS = [
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
+            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and "optional":true to any step that may legitimately have nothing to act on, which is how you cross a first-launch nag, a permission sheet or a "What\'s New" in one batch — {"tap":"Not Now","optional":true} is skipped when nothing matches and runs normally when it does, so the rest of the plan survives an interstitial that did not appear — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
           items: { type: 'object' },
         },
         autoSettle: {
@@ -1046,12 +1047,55 @@ async function doScript(target, args, options) {
     lines.push(`supervisor at step ${s_.index}: ${s_.decision} — ${s_.outcome}`
       + (s_.reason ? ` (it said: "${s_.reason}")` : ''));
   }
+  // **A brief with nobody to read it says so.**
+  //
+  // `supervise` is standing guidance for a supervisor; *which* supervisor comes
+  // from `options.supervisor` or SIMFRAME_SUPERVISOR, and with neither set the
+  // brief is discarded. The code even documented that as "always safe" — safe
+  // and silent, which is the trap. Two independent field reports hit it: both
+  // passed a brief on every call, neither ever saw a verdict, and one had
+  // written guidance describing the exact race that then aborted their batch.
+  // Their words: "as written, `supervise` is a prompt I can't observe the
+  // effect of."
+  //
+  // Said only when a brief was actually passed, so it is never noise, and it
+  // names the remedy rather than the condition.
+  if (args.supervise && !supervisor.requested(options)) {
+    lines.push('supervisor: none enabled, so the "supervise" brief was not consulted'
+      + ' — set supervisor (per call) or SIMFRAME_SUPERVISOR to enable one.');
+  } else if (args.supervise && !(res.supervisions ?? []).length) {
+    lines.push(`supervisor: ${supervisor.requested(options)} enabled, never consulted`
+      + ' — no step failed in a way that asks for a ruling.');
+  }
   if (args.saveAs) {
     const saved = navigate.saveFlow(res.device.udid, args.saveAs, res);
+    // Say what to do about it. The refusal this replaced named a condition and
+    // no remedy, and the reporter read it as "recording a flow is impossible"
+    // — which it was.
+    const how = saved.provisional
+      ? ' — PROVISIONAL, because this was the first traversal and nothing had been'
+        + ' seen before to compare against. Replay it once with sim_flow_run and it'
+        + ' is confirmed. A replay costs no model calls.'
+      : ' — confirmed; replay with sim_flow_run for zero model calls';
+    // One sentence per reason, because "incomplete-run" and "failed-steps" ask
+    // for opposite things from the caller and the bare reason names neither.
+    const why = {
+      'contradicted-steps': 'a step landed somewhere memory says it should not have,'
+        + ' so this route is not safe to replay. Check the flagged step before re-running it.',
+      'failed-steps': 'a step ran and failed, so replaying this would fail the same way'
+        + ' every time. Fix the step and re-run the batch, then save.',
+      'incomplete-run': 'the run stopped before its last step, so the rest of the route'
+        + ' was never observed. Re-run it to the end, then save.',
+    }[saved.reason];
+    // `verdicts` has a hole wherever a step never produced one — a failed step
+    // has no verification — and joining those printed `(unverified, unverified, )`.
+    const seen = (saved.verdicts ?? []).filter(Boolean);
     lines.push(
       saved.ok
-        ? `saved as flow "${saved.name}" (${saved.steps} steps) — replay with sim_flow_run`
-        : `NOT saved as "${args.saveAs}": ${saved.reason}${saved.verdicts ? ` (${saved.verdicts.join(', ')})` : ''}`,
+        ? `saved as flow "${saved.name}" (${saved.steps} steps)${how}`
+        : `NOT saved as "${args.saveAs}": ${saved.reason}`
+          + `${why ? ` — ${why}` : ''}`
+          + `${seen.length ? ` (verdicts: ${seen.join(', ')})` : ''}`,
     );
   }
   const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));
@@ -1137,6 +1181,14 @@ async function flowRun(target, args, options) {
     };
   }
   const lines = [`flow "${args.name}"`, ...stepLines(res)];
+  // Said out loud or not said at all. A flow now records the screen it was
+  // recorded on, and a mismatch that only exists in the return value is a fact
+  // nobody reads — which is the same shape as the check that could not fail.
+  if (res.startedElsewhere) {
+    lines.push(`NOTE: this flow was recorded starting on screen ${res.startedElsewhere.recorded},`
+      + ` and this replay started on ${res.startedElsewhere.here}. Not refused — content-driven`
+      + ' screens legitimately change identity — but if the steps below fail to resolve, this is why.');
+  }
   lines.push('', await mapFrom(target, options, res.endScreen, { verdictLine: verdictLineFor(res.results) }));
   return { content: [text(lines.join('\n'))], isError: !res.ok };
 }

package/src/metrics.js

@@ -654,7 +654,12 @@ export function hpi({ flows, baselines = {} }) {
     const agent = quartiles(finished.map((r) => r.wall_time_ms));
     const human = baselines[name]?.wall_time_ms ?? null;
     const humanMedian = human?.p50 ?? null;
-    const stepRatios = runs.map((r) => r.step_ratio).filter((x) => Number.isFinite(x));
+    // Completed runs only, for the same reason the time is: a run that stops
+    // three steps in reports a LOW step ratio, so breakage flattered this
+    // number too. The runner's suite, with 3 of 14 runs completing, reported
+    // `step_ratio 0.375` — "the agent uses a third of the human's steps" about
+    // flows that mostly never arrived.
+    const stepRatios = finished.map((r) => r.step_ratio).filter((x) => Number.isFinite(x));
     return {
       flow: name,
       runs: runs.length,
@@ -667,6 +672,22 @@ export function hpi({ flows, baselines = {} }) {
       wrong_action: runs.filter((r) => r.wrong_action_taken).length,
       escalations: runs.reduce((acc, r) => acc + (r.escalation_count ?? 0), 0),
       model_turns: median(runs.map((r) => r.model_turns)),
+      // **The latency lever, and it was already in the log unsurfaced.**
+      //
+      // Wall-clock per step is dominated by the model round trip, not by
+      // simframe: measured in the field, ~20 s of agent latency against ~1.7 s
+      // of simframe work per step. So per-step time is
+      // `(20s + 1.7s x n) / n` for n steps in one call — 21.7 s at n=1, 11.7 s
+      // at n=2, 6.7 s at n=4. Nothing about making simframe faster moves that;
+      // only n does.
+      //
+      // Which makes this the number to watch, and every hard-fail that drops a
+      // caller back to single-stepping a latency regression. Over 186 recorded
+      // runs on the author's device the median was 2.0 and the 25th percentile
+      // 1.0 — the p25 tail is recovery, and it is where the time goes.
+      steps_per_call: median(runs
+        .filter((r) => Number.isFinite(r.steps_taken) && r.model_turns > 0)
+        .map((r) => r.steps_taken / r.model_turns)),
     };
   }).sort((a, b) => a.flow.localeCompare(b.flow));
 
@@ -684,6 +705,9 @@ export function hpi({ flows, baselines = {} }) {
       hpi_accuracy: accuracy,
       hpi_time: hpiTime == null ? null : Number(hpiTime.toFixed(3)),
       hpi: hpiTime == null || accuracy == null ? null : Number((accuracy * hpiTime).toFixed(3)),
+      steps_per_call: median(flows
+        .filter((f) => Number.isFinite(f.steps_taken) && f.model_turns > 0)
+        .map((f) => f.steps_taken / f.model_turns)),
       step_ratio: median(perFlow.map((f) => f.step_ratio)),
       model_turns_median: median(perFlow.map((f) => f.model_turns)),
     },
@@ -799,8 +823,34 @@ export function breakdown(records, { session = null, flow = null } = {}) {
  * than one, and accuracy stays strict at any drop at all. Numbers in
  * docs/BENCHMARKS.md under "What the gate is set to, and why".
  */
+/**
+ * The band HPI_time is *reported* against. It no longer fails a build.
+ *
+ * It was a gate, at 25% here and written down as 10% in CLAUDE.md — and the
+ * measurement cannot support either. `HPI_time` is `human_p50 / agent_p50`
+ * where the human was recorded once, on a laptop, and the agent is measured
+ * wherever CI happens to run: a hosted runner put the same flows at 37 s and
+ * 64 s against 11.5 s and 11.7 s on that laptop, so the ratio mixes the code's
+ * speed with the host's. Even on one machine, identical code spans 0.406-0.558
+ * across device conditions — a 37% spread. A band inside that can only be
+ * silent or wrong, and it was silent: items 148, 152, 154 and 169 all shipped
+ * without it firing.
+ *
+ * So time is a trend, per host, and accuracy is the gate. Accuracy asks
+ * whether the agent reached the destination and whether it tapped the wrong
+ * thing — properties of the code, not of the machine.
+ */
 export const TIME_REGRESSION = 0.25;
 
+/**
+ * The most steps-per-human-step we will accept. From the research: an agent
+ * taking half again as many actions as a person is wandering.
+ *
+ * An absolute target rather than a regression, deliberately — it is a ratio of
+ * two step counts, so unlike the time it does not change with the host.
+ */
+export const STEP_RATIO_CEILING = 1.5;
+
 /**
  * The HPI_time a gate should compare: the median across passes when a report
  * has them, and the single measurement when it does not — so a baseline
@@ -816,7 +866,7 @@ export const gateTime = (o) => o?.hpi_time_median_of_passes ?? o?.hpi_time ?? nu
  * fingerprint eval both shipped unable to fail, and both looked exactly like
  * this. Returns the reasons it should fail — empty means pass.
  */
-export function gateAgainst(baseline, measured, { timeRegression = TIME_REGRESSION } = {}) {
+export function gateAgainst(baseline, measured, { stepRatioCeiling = STEP_RATIO_CEILING } = {}) {
   const base = baseline?.overall ?? {};
   const now = measured?.overall ?? measured ?? {};
   const baseTime = gateTime(base);
@@ -825,19 +875,44 @@ export function gateAgainst(baseline, measured, { timeRegression = TIME_REGRESSI
   if (base.hpi_accuracy != null && now.hpi_accuracy != null && now.hpi_accuracy < base.hpi_accuracy) {
     failures.push(`HPI_accuracy dropped: ${now.hpi_accuracy} < ${base.hpi_accuracy} (any drop fails)`);
   }
-  if (baseTime != null && nowTime != null && nowTime < baseTime * (1 - timeRegression)) {
+  // Steps, which the host cannot inflate: a ratio of two step counts.
+  if (now.step_ratio != null && now.step_ratio > stepRatioCeiling) {
     failures.push(
-      `HPI_time regressed >${timeRegression * 100}%: ${nowTime} < ${(baseTime * (1 - timeRegression)).toFixed(3)}`,
+      `step_ratio ${now.step_ratio} is above the ${stepRatioCeiling} ceiling — the agent is taking more actions than a person`,
     );
   }
-  // A checkout missing the human baseline the committed number was computed
-  // against would otherwise pass by having nothing to compare.
+  // **HPI_time does not fail a build.** See TIME_REGRESSION. It is reported
+  // with its band so a trend is visible and a big move is obvious to a human,
+  // and `timeTrend` below is what prints it.
+  //
+  // A checkout missing the human baseline is still a failure, because it is a
+  // broken measurement rather than a slow one — a report with no time at all
+  // would otherwise pass by having nothing to say.
   if (baseTime != null && nowTime == null) {
     failures.push('HPI_time is null but the baseline has one — the human baseline it needs is missing from this checkout');
   }
   return failures;
 }
 
+/**
+ * HPI_time as a line to read, never a verdict.
+ *
+ * Says how far it moved and whether that is outside the reporting band, and
+ * says plainly that it is not a gate — a CI line that looks like a threshold
+ * gets read as one.
+ */
+export function timeTrend(baseline, measured, { timeRegression = TIME_REGRESSION } = {}) {
+  const baseTime = gateTime(baseline?.overall ?? {});
+  const nowTime = gateTime(measured?.overall ?? measured ?? {});
+  if (baseTime == null || nowTime == null) return 'HPI_time — not comparable (one side has no measurement)';
+  const delta = (nowTime - baseTime) / baseTime;
+  const pct = `${delta >= 0 ? '+' : ''}${(delta * 100).toFixed(1)}%`;
+  const wide = Math.abs(delta) > timeRegression;
+  return `HPI_time ${baseTime} -> ${nowTime} (${pct})`
+    + `${wide ? ` — outside the ${timeRegression * 100}% reporting band, worth a look` : ''}`
+    + ' — reported, not gated: this ratio mixes the code with the host';
+}
+
 /** A flow id that sorts by time and is short enough to read in a log. */
 export function newFlowId() {
   return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;

package/src/navigate.js

@@ -139,18 +139,69 @@ export function knownScreens(udid) {
   return graph.allNodes(udid).map((n) => ({ name: graph.describe(n) ?? n.hash.slice(0, 8), hash: n.hash.slice(0, 8), edges: n.edges.length }));
 }
 
+/**
+ * A verdict that is evidence *against* a step, as opposed to no evidence yet.
+ *
+ * This distinction is the whole of the fix below. `unexpected-*` means the step
+ * did something other than what memory predicted — a real objection. `unverified`
+ * means this edge has never been walked before, which on a first traversal is
+ * true of every step by definition and says nothing about whether it worked.
+ */
+const CONTRADICTED = /^unexpected/;
+
 /**
  * Save a flow.
  *
- * Only flows that verified end to end are worth saving: a flow with an
- * unverified step in it is a recording of something that may not have worked,
- * and replaying it faithfully reproduces the doubt.
+ * The rule was "only flows that verified end to end", and it was right about
+ * replay safety and wrong about arithmetic: **a first successful traversal is
+ * all-`unverified` by construction**, so nothing could ever be recorded, so
+ * `sim_flow_run` was unreachable. A field report hit it on a clean 10-of-10
+ * batch — *"I never obtained a saved flow, so `sim_flow_run` went untested"* —
+ * and it matters far more than its severity suggests: a replayed flow costs
+ * **zero model calls**, which is the only path to human-level wall clock. A
+ * gate nobody can pass protects nothing and blocks the fastest thing here.
+ *
+ * So the refusal now needs evidence against a step, not the absence of evidence
+ * for it. A flow that ran every step with nothing contradicted saves as
+ * **provisional**, and one clean replay promotes it — a bootstrap in two runs,
+ * where the second run is the confirmation and is useful anyway.
+ *
+ * Still refused, because these are real objections: any `unexpected-*` verdict,
+ * and a flow that did not reach its own last step.
  */
 export function saveFlow(udid, name, script, { force = false } = {}) {
-  const verdicts = (script.results ?? []).map((r) => r.verification?.verdict);
-  if (!force && verdicts.some((v) => v && v !== 'ok')) {
-    return { ok: false, reason: 'unverified-steps', verdicts };
+  const results = script.results ?? [];
+  const verdicts = results.map((r) => r.verification?.verdict);
+  const contradicted = verdicts.filter((v) => v && CONTRADICTED.test(v));
+  const ranAll = script.ranSteps == null
+    || script.steps == null
+    || script.ranSteps >= (script.steps?.length ?? 0);
+  // A step that ran and failed is not a step that ran.
+  //
+  // `ranSteps` counts steps *attempted*, and a failing step stops the batch —
+  // so a run whose failure is on the **last** step has `ranSteps === steps.length`
+  // and passed the gate above. A peer watched `FLOW FAILED — 4 ok, 1 failed (of
+  // 5)` save itself as a flow, which is a flow guaranteed to fail forever. The
+  // predicate wanted "every step succeeded" and was written as "every step was
+  // reached"; on every run except one they are the same sentence.
+  //
+  // `!r.ok` rather than `r.ok === false` on purpose: a result that does not say
+  // it succeeded has not said it succeeded, and a gate that only catches an
+  // explicit `false` is one absent field away from being unable to fail.
+  const failedSteps = results.filter((r) => !r.ok);
+  if (!force && contradicted.length) {
+    return { ok: false, reason: 'contradicted-steps', verdicts };
+  }
+  if (!force && failedSteps.length) {
+    return { ok: false, reason: 'failed-steps', verdicts, failed: failedSteps.map((r) => r.index ?? null) };
   }
+  if (!force && !ranAll) {
+    return { ok: false, reason: 'incomplete-run', verdicts };
+  }
+  // Provisional whenever any step lacked a confirming verdict. Recorded on the
+  // flow rather than inferred later, so a replay can promote it and a listing
+  // can say which flows are still on their first observation.
+  const provisional = verdicts.some((v) => !v || v !== 'ok');
   const dir = flowDir(udid);
   fs.mkdirSync(dir, { recursive: true });
   const body = {
@@ -158,9 +209,28 @@ export function saveFlow(udid, name, script, { force = false } = {}) {
     savedAt: Date.now(),
     steps: script.steps ?? (script.results ?? []).map((r) => r.step).filter(Boolean),
     startScreen: script.startScreen ?? null,
+    ...(provisional ? { provisional: verdicts.filter(Boolean) } : {}),
   };
   store.writeAtomic(path.join(dir, `${encodeURIComponent(name)}.json`), JSON.stringify(body, null, 2));
-  return { ok: true, name, steps: body.steps.length };
+  return { ok: true, name, steps: body.steps.length, provisional };
+}
+
+/**
+ * A provisional flow that replays cleanly becomes a confirmed one.
+ *
+ * The second half of the bootstrap. Without it "provisional" would be a label
+ * that never comes off, and the honest state of a flow that has now worked
+ * twice is "confirmed".
+ */
+export function confirmFlow(udid, name) {
+  const flow = loadFlow(udid, name);
+  if (!flow?.provisional) return false;
+  const { provisional, ...rest } = flow;
+  store.writeAtomic(
+    path.join(flowDir(udid), `${encodeURIComponent(name)}.json`),
+    JSON.stringify({ ...rest, confirmedAt: Date.now() }, null, 2),
+  );
+  return true;
 }
 
 export function loadFlow(udid, name) {
@@ -174,7 +244,18 @@ export function listFlows(udid) {
     .filter((f) => f.endsWith('.json'))
     .map((f) => store.readJson(path.join(dir, f)))
     .filter(Boolean)
-    .map((f) => ({ name: f.name, steps: f.steps?.length ?? 0, savedAt: f.savedAt }));
+    // `provisional` travels with the listing, for two reasons. A caller should
+    // be able to see which of their flows are still on a first observation
+    // without opening the file — and without it the integration check that
+    // asserts promotion reads `undefined`, which is always falsy, so the check
+    // would pass whether or not anything was promoted. A vacuous check is worse
+    // than no check.
+    .map((f) => ({
+      name: f.name,
+      steps: f.steps?.length ?? 0,
+      savedAt: f.savedAt,
+      ...(f.provisional ? { provisional: true } : {}),
+    }));
 }
 
 export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}) {
@@ -185,6 +266,28 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
   // a human doing the same thing. `minSteps` comes from the flow definition or
   // stays null — the step count of a recorded route is not a claim about the
   // shortest one.
+  // Is this the screen the flow was recorded on?
+  //
+  // Reported, not refused, and the distinction is deliberate. A replay from the
+  // wrong screen is mostly self-limiting — the first selector does not resolve
+  // and the run stops one step in, and the destructive vocabulary is barred by
+  // the verify barrier either way. Refusing on a mismatch would put the exact
+  // failure mode of item 174 — content-driven screens fragmenting into several
+  // identities — in front of the one path that costs zero model calls. So this
+  // says what it saw and lets the run proceed, which also measures how often
+  // the mismatch is spurious. If it turns out to be rare, it can become a gate;
+  // deciding that by reasoning is how 174 got built in the first place.
+  let startedElsewhere = null;
+  if (flow.startScreen?.hash) {
+    try {
+      const here = await api.screenIdentity(device.udid, {});
+      if (here.hash && !graph.sameScreen(device.udid, here, flow.startScreen)) {
+        startedElsewhere = { recorded: flow.startScreen.hash.slice(0, 8), here: here.hash.slice(0, 8) };
+      }
+    } catch {
+      /* not knowing where we are is not a reason to refuse to try */
+    }
+  }
   const result = await runScript(device.udid, {
     steps: flow.steps,
     stopOnUnexpected: true,
@@ -192,5 +295,18 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
     minSteps: flow.minSteps ?? null,
     ...runOptions,
   });
-  return { ok: result.ranSteps === flow.steps.length, name, ...result };
+  // Same arithmetic as `saveFlow`, and the same defect: reaching the last step
+  // is not passing it. `result.ok` is the run's own verdict and was ignored
+  // here, so a replay that failed on its final assert promoted the flow it had
+  // just disproved. Both of a peer's saved flows were marked confirmed by
+  // replays that failed; the word "clean" in "confirmed by one clean replay"
+  // did not exist in the code path.
+  const everyStepPassed = (result.results ?? []).every((r) => r.ok);
+  const ok = result.ok !== false && everyStepPassed && result.ranSteps === flow.steps.length;
+  // A clean replay is the confirmation a first traversal could not give.
+  // Only when nothing was contradicted — a replay that ran to the end while
+  // objecting to a step is not a promotion.
+  const objected = (result.results ?? []).some((r) => CONTRADICTED.test(r.verification?.verdict ?? ''));
+  const promoted = ok && !objected ? confirmFlow(device.udid, name) : false;
+  return { ok, name, ...result, ...(promoted ? { promoted: true } : {}), ...(startedElsewhere ? { startedElsewhere } : {}) };
 }