simframe 0.15.0 → 0.16.0

package/README.md

@@ -701,6 +701,36 @@ 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
+```
+
+| | per step |
+| --- | --- |
+| a human tester, measured | **1.95 s** |
+| **a saved flow replayed — zero model calls** | **1.98 s** |
+| simframe's own work inside a batch | **~1.7 s** |
+| a batch of 4 steps, one model call | ~6.7 s |
+| a batch of 2 steps | ~11.7 s |
+| one model call per step | ~21.7 s |
+
+**A replayed flow runs at human speed**, and simframe's own work already does.
+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.0",
+  "version": "0.16.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

@@ -186,11 +186,7 @@ const report = {
 
 console.log('\nflow                      runs  agent p50   human p50   HPI_time  step_ratio');
 for (const f of report.flows) {
-  console.log(
-    `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
-      `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
-      `${String(f.hpi_time ?? '—').padStart(8)}  ${String(f.step_ratio ?? '—').padStart(10)}`,
-  );
+  console.log(metrics.flowRow(f));
 }
 report.overall.hpi_time_median_of_passes = passTimes.length ? Number(metrics.median(passTimes).toFixed(3)) : null;
 const o = report.overall;
@@ -247,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,31 @@ 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 });
+const contradicted = attempt.results.some((r) => /^unexpected/.test(r.verification?.verdict ?? ''));
 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 {
+  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 +672,17 @@ 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.
+  if (replayed.ok) {
+    const after = await jsonRetry(['flow', 'list']);
+    const entry = after.find((f) => f.name === FLOW_NAME);
+    check(entry && !entry.provisional,
+      'and a clean replay confirms a provisional flow',
+      `provisional=${entry?.provisional ?? 'gone'}`);
+  }
   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.
@@ -1559,12 +1582,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 +2199,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 +2374,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 +2404,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 +2412,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 +2427,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 +2896,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 +2941,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.

package/src/cli.js

@@ -1234,11 +1234,7 @@ async function main() {
       emit(flags, report, [
         flags.last ? `the last ${num(flags.last)} run(s) of each flow, of ${all.filter((f) => f.flow_name).length} named runs in the log` : null,
         'flow                      runs  agent p50   human p50   HPI_time  step_ratio  turns  esc',
-        ...report.flows.map((f) =>
-          `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  ${`${f.agent_ms.p50}ms`.padStart(9)}   ` +
-          `${(f.human_median_ms ? `${f.human_median_ms}ms` : '—').padStart(9)}   ` +
-          `${(f.hpi_time ?? '—').toString().padStart(8)}  ${(f.step_ratio ?? '—').toString().padStart(10)}  ` +
-          `${(f.model_turns ?? '—').toString().padStart(5)}  ${String(f.escalations).padStart(3)}`),
+        ...report.flows.map((f) => metrics.flowRow(f, { wide: true })),
         '',
         `HPI_accuracy ${report.overall.hpi_accuracy} (${report.overall.runs} runs, ` +
           `${report.overall.runs - runs.filter((r) => r.completed && !r.wrong_action_taken).length} not clean)`,
@@ -1246,6 +1242,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/matching.js

@@ -220,7 +220,48 @@ 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: `waitFor "6322594"` gave up after 20 s on a screen
+  // whose own "Visible:" list printed `Work Order #6322594`. 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';
@@ -1046,12 +1047,41 @@ 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';
     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}`
+          + `${saved.verdicts ? ` (${saved.verdicts.join(', ')})` : ''}`,
     );
   }
   const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));

package/src/metrics.js

@@ -601,6 +601,30 @@ export function harmonicMean(xs) {
  * a human baseline. A flow with no human baseline gets no HPI_time — reported
  * as null, never as 1.0, because a missing denominator is not parity.
  */
+/**
+ * One flow's row in the HPI table, shared by `simframe hpi` and the bench
+ * script because they had the same row duplicated byte for byte.
+ *
+ * It lives here, next to the report it renders, for a reason the v0.15.0 tag
+ * paid for: making `agent_ms` null for a flow that timed nothing was correct,
+ * and both printers dereferenced `.p50` on it. `bench` died with exit 1 and no
+ * hpi.json, and `simframe hpi` would have done the same for any user whose
+ * flow never completed. The metric had a test; nothing rendered it. A format
+ * duplicated in two files is a format that gets fixed in one.
+ *
+ * `—` means "not measured", never zero.
+ */
+export function flowRow(f, { wide = false } = {}) {
+  const cell = (v, unit = '') => (v === null || v === undefined ? '—' : `${v}${unit}`);
+  const row = `${f.flow.padEnd(24)} ${String(f.runs).padStart(5)}  `
+    + `${cell(f.agent_ms?.p50, 'ms').padStart(9)}   `
+    + `${cell(f.human_median_ms, 'ms').padStart(9)}   `
+    + `${cell(f.hpi_time).padStart(8)}  ${cell(f.step_ratio).padStart(10)}`;
+  return wide
+    ? `${row}  ${cell(f.model_turns).padStart(5)}  ${String(f.escalations).padStart(3)}`
+    : row;
+}
+
 export function hpi({ flows, baselines = {} }) {
   const byName = new Map();
   for (const f of flows) {
@@ -630,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,
@@ -643,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));
 
@@ -660,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)),
     },
@@ -775,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
@@ -792,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);
@@ -801,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,52 @@ 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 contradicted = verdicts.filter((v) => v && CONTRADICTED.test(v));
+  const ranAll = script.ranSteps == null
+    || script.steps == null
+    || script.ranSteps >= (script.steps?.length ?? 0);
+  if (!force && contradicted.length) {
+    return { ok: false, reason: 'contradicted-steps', verdicts };
   }
+  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 +192,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 +227,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 } = {}) {
@@ -192,5 +256,11 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
     minSteps: flow.minSteps ?? null,
     ...runOptions,
   });
-  return { ok: result.ranSteps === flow.steps.length, name, ...result };
+  const ok = 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 } : {}) };
 }