simframe 0.16.0 → 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"*. |
@@ -710,16 +722,35 @@ 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.
+**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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.16.0",
+  "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/ci-memory.mjs

@@ -646,12 +646,25 @@ console.log('\n--- what may be saved, and what may not ---');
 // 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 (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`);
@@ -676,12 +689,21 @@ if (check(forced.saved?.ok === true, 'and --force saves it anyway', `${forced.sa
   // 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) {
-    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'}`);
+  } 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

@@ -346,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.
@@ -393,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 {
@@ -945,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({
@@ -1020,6 +1060,7 @@ export async function runScript(
     // navigate.saveFlow without the caller reassembling what it just ran.
     steps,
     flowId,
+    startScreen,
     endScreen,
     results,
     ok: !failed,
@@ -1462,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));
@@ -3246,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 }),
         ]);

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

@@ -224,8 +224,9 @@ export function rank(targets, intent, { screen } = {}) {
 
   // **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
+  // 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

package/src/mcp.js

@@ -134,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: {
@@ -1077,11 +1077,25 @@ async function doScript(target, args, options) {
         + ' 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)${how}`
         : `NOT saved as "${args.saveAs}": ${saved.reason}`
-          + `${saved.verdicts ? ` (${saved.verdicts.join(', ')})` : ''}`,
+          + `${why ? ` — ${why}` : ''}`
+          + `${seen.length ? ` (verdicts: ${seen.join(', ')})` : ''}`,
     );
   }
   const escalated = (res.results ?? []).some((r) => metrics.ESCALATING_VERDICTS.has(r.verification?.verdict));
@@ -1167,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/navigate.js

@@ -170,14 +170,31 @@ const CONTRADICTED = /^unexpected/;
  * 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);
+  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 };
   }
@@ -249,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,
@@ -256,11 +295,18 @@ export async function runFlow(deviceQuery, name, { options, ...runOptions } = {}
     minSteps: flow.minSteps ?? null,
     ...runOptions,
   });
-  const ok = result.ranSteps === flow.steps.length;
+  // 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 } : {}) };
+  return { ok, name, ...result, ...(promoted ? { promoted: true } : {}), ...(startedElsewhere ? { startedElsewhere } : {}) };
 }