simframe 0.4.1 → 0.5.0

package/scripts/bench-flow.mjs

@@ -0,0 +1,54 @@
+// Times a realistic navigation flow end to end, and reports where the time went.
+// Used to check that the input driver works at all, and to measure sim_do.
+import { runScript } from '../src/actions.js';
+import * as input from '../src/input.js';
+import * as api from '../src/index.js';
+import { launchApp, terminateApp } from '../src/simctl.js';
+
+const BUNDLE = process.argv[2];
+const device = process.argv[3];
+
+if (!BUNDLE) {
+  console.error('usage: node scripts/bench-flow.mjs <bundle-id> [device]');
+  process.exit(2);
+}
+
+const driver = await input.detectDriver();
+console.log(`driver: ${driver.available ? driver.version : driver.reason}`);
+if (!driver.available) process.exit(1);
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})`);
+const geo = await input.screenInfo(dev.udid);
+console.log(`screen: ${geo.pixelWidth}x${geo.pixelHeight}px @${geo.density}x = ${geo.pointWidth}x${geo.pointHeight}pt\n`);
+
+const t0 = Date.now();
+try { await terminateApp(dev.udid, BUNDLE); } catch { /* not running */ }
+await launchApp(dev.udid, BUNDLE);
+const launched = await api.waitFor(device, { mode: 'settle', stableMs: 800, timeoutMs: 20_000 });
+console.log(`cold launch + settle: ${Date.now() - t0}ms (satisfied=${launched.satisfied})`);
+
+const nodes = await input.describeAll(dev.udid);
+console.log(`accessibility tree: ${nodes.length} elements`);
+const labelled = nodes.filter((n) => n.label && n.frame.width > 8 && n.frame.height > 8);
+console.log('\nlabelled elements (type, tap point, label):');
+for (const n of labelled.slice(0, 40)) {
+  const c = input.centerOf(n);
+  console.log(`  ${(n.type || '?').padEnd(14)} ${String(`${c.x},${c.y}`).padEnd(10)} ${n.label}`);
+}
+
+// Anything sitting in the bottom eighth of the screen is probably a tab bar.
+const tabs = labelled.filter((n) => n.frame.y > geo.pointHeight * 0.86);
+console.log(`\nlikely tab bar: ${tabs.map((t) => t.label).join(', ') || '(none found)'}`);
+
+if (tabs.length >= 2) {
+  const steps = tabs.slice(0, 4).map((t) => ({ tap: t.label }));
+  console.log(`\nrunning ${steps.length} tab switches as ONE sim_do call...`);
+  const t1 = Date.now();
+  const res = await runScript(device, { steps, stableMs: 500, timeoutMs: 10_000 });
+  for (const r of res.results) {
+    console.log(`  ${r.ok ? 'ok  ' : 'FAIL'} ${r.action}: ${r.ok ? r.detail : r.error}` +
+      (r.settled ? ` (settled ${r.settled.waitedMs}ms, changed=${r.settled.sawChange})` : ''));
+  }
+  console.log(`\n${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${Date.now() - t1}ms`);
+}

package/scripts/bench.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Reproduces every number in docs/BENCHMARKS.md.
+#
+# Needs a booted simulator. Numbers are medians; the first sample of anything
+# involving Vision is discarded, because its warm-up dwarfs the measurement.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+DEVICE="${1:-}"
+BIN=native/simframed/.build/release/simframed
+
+say() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+say "environment"
+printf '  chip    %s\n' "$(sysctl -n machdep.cpu.brand_string 2>/dev/null)"
+printf '  macOS   %s\n' "$(sw_vers -productVersion)"
+printf '  Xcode   %s\n' "$(xcodebuild -version 2>/dev/null | head -1)"
+
+say "building simframed (release)"
+swift build -c release --package-path native/simframed 2>&1 | tail -1
+
+UDID="$DEVICE"
+if [ -z "$UDID" ]; then
+  UDID=$($BIN devices | head -1 | awk '{print $1}')
+fi
+if [ -z "$UDID" ]; then
+  echo "  no booted simulator; boot one and re-run" >&2
+  exit 1
+fi
+printf '  device  %s\n' "$($BIN devices | grep "$UDID" | cut -c40-)"
+
+say "capture pipeline (Phase 0)"
+$BIN bench --udid="$UDID" --n=300 | sed 's/^/  /'
+$BIN bench --udid="$UDID" --n=300 --max-dim=420 | sed 's/^/  /'
+
+say "simctl + sips, the path it replaces"
+for _ in 1 2 3 4 5; do
+  /usr/bin/time -p sh -c "xcrun simctl io $UDID screenshot --type=png --mask=ignored /tmp/bench.png >/dev/null 2>&1 && sips -Z 700 /tmp/bench.png --out /tmp/bench-s.png >/dev/null 2>&1" 2>&1 | grep real
+done | awk '{s+=$2; n++} END {printf "  mean %.0f ms over %d runs\n", s/n*1000, n}'
+
+say "hash compatibility (Swift vs JavaScript, needs a still screen)"
+node -e '
+const { execSync } = require("child_process");
+(async () => {
+  const api = await import("./src/index.js");
+  const { hashDistance } = await import("./src/analyze.js");
+  let a, b;
+  for (let i = 0; i < 25; i++) {
+    a = (await api.getState(undefined, {})).state;
+    await new Promise(r => setTimeout(r, 1000));
+    b = (await api.getState(undefined, {})).state;
+    if (a.hash === b.hash && a.layoutHash === b.layoutHash) break;
+  }
+  if (a.hash !== b.hash) { console.log("  screen never settled; skipped"); return; }
+  const sw = JSON.parse(execSync("native/simframed/.build/release/simframed hash").toString());
+  console.log(`  frameHash  delta ${hashDistance(b.hash, sw.hash)}/128`);
+  console.log(`  layoutHash delta ${hashDistance(b.layoutHash, sw.layoutHash)}/288`);
+})()' 2>/dev/null
+
+say "control socket round trips (Phase 1)"
+node -e '
+import("./src/control.js").then(async (c) => {
+  const UD = process.argv[1];
+  const med = a => { const s=[...a].sort((x,y)=>x-y); return s[s.length>>1]; };
+  const bench = async (label, fn, n) => {
+    const t = []; for (let i=0;i<n;i++){ const t0=Date.now(); await fn(i); t.push(Date.now()-t0); }
+    console.log(`  ${label.padEnd(22)} n=${String(n).padStart(3)}  median ${med(t)}ms`);
+  };
+  await bench("ping", () => c.request(UD,{action:"ping"}), 100);
+  await bench("status", () => c.status(UD), 50);
+  await bench("tap (70ms hold)", i => c.tap(UD, 200+(i%3), 300), 100);
+  await bench("tap (10ms hold)", i => c.tap(UD, 200+(i%3), 300, {durationMs:10}), 100);
+})' "$UDID" 2>/dev/null
+
+say "text recognition (Phase 2)"
+node -e '
+import("./src/control.js").then(async (c) => {
+  const UD = process.argv[1];
+  const med = a => { const s=[...a].sort((x,y)=>x-y); return s[s.length>>1]; };
+  const t=[]; for (let i=0;i<12;i++){ const t0=Date.now(); await c.request(UD,{action:"ui"}); t.push(Date.now()-t0); }
+  // Drop the first: Vision warm-up dwarfs it.
+  console.log(`  in-process   first ${t[0]}ms  median ${med(t.slice(1))}ms`);
+})' "$UDID" 2>/dev/null
+
+say "screen map build (Phase 2)"
+node -e '
+import("./src/index.js").then(async (api) => {
+  const UD = process.argv[1];
+  for (const pass of [1,2,3]) {
+    api.screenmap.forget(UD);
+    const t0 = Date.now();
+    try { await api.locate(undefined, "a", {}); } catch { /* the label need not exist */ }
+    console.log(`  build ${pass}: ${Date.now()-t0}ms`);
+  }
+})' "$UDID" 2>/dev/null
+
+say "done — compare against docs/BENCHMARKS.md"

package/scripts/check-package.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Does the tarball contain everything the installed tool needs?
+//
+// This is the cheapest catch for the two worst regressions this project has
+// shipped, both of which passed every test and printed nothing:
+//
+//   - `Tests/` was absent, so Package.swift declared a test target with no
+//     directory, SwiftPM reported overlapping sources, and every install
+//     silently fell back to the simctl engine.
+//   - `native/ocr.swift` was absent, so OCR was silently off for all users.
+//
+// The required list is DERIVED from what the build actually reads, never
+// hand-maintained. A hand-written list is how `files` rotted in the first
+// place: it was correct when written and wrong three commits later. Add a new
+// Swift source or a new module here and it becomes required automatically.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const rel = (p) => path.relative(ROOT, p).split(path.sep).join('/');
+
+function walk(dir, filter, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    // .build holds compiled output, not inputs, and is never published.
+    if (e.isDirectory()) {
+      if (e.name === '.build' || e.name === 'node_modules') continue;
+      walk(full, filter, out);
+    } else if (filter(full)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Everything the SwiftPM build and the Node runtime read at install or run time. */
+function requiredFiles() {
+  const swiftPackage = path.join(ROOT, 'native', 'simframed');
+  const required = new Set();
+
+  // The SwiftPM manifest, and every source under the targets it declares.
+  required.add(rel(path.join(swiftPackage, 'Package.swift')));
+  for (const dir of ['Sources', 'Tests']) {
+    for (const f of walk(path.join(swiftPackage, dir), (p) => p.endsWith('.swift'))) {
+      required.add(rel(f));
+    }
+  }
+  // Test targets are build inputs whether or not anyone runs them: a declared
+  // target with a missing directory fails the whole build.
+  if (!walk(path.join(swiftPackage, 'Tests'), (p) => p.endsWith('.swift')).length) {
+    throw new Error('no Swift test sources found — has the layout moved? This check would silently pass.');
+  }
+
+  // The standalone OCR helper, compiled on demand by src/ocr.js.
+  required.add(rel(path.join(ROOT, 'native', 'ocr.swift')));
+
+  // Every runtime module. `files` ships "src" wholesale today; asserting each
+  // one catches anybody narrowing that later.
+  for (const f of walk(path.join(ROOT, 'src'), (p) => p.endsWith('.js'))) required.add(rel(f));
+
+  // Anything package.json points at to run.
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  for (const target of Object.values(pkg.bin ?? {})) required.add(target.replace(/^\.\//, ''));
+  if (pkg.main) required.add(pkg.main.replace(/^\.\//, ''));
+
+  return [...required].sort();
+}
+
+const required = requiredFiles();
+const packed = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--json'], { cwd: ROOT, encoding: 'utf8' }));
+const shipped = new Set(packed[0].files.map((f) => f.path));
+const missing = required.filter((f) => !shipped.has(f));
+
+console.log(`${required.length} build inputs required, ${shipped.size} files in the tarball`);
+for (const f of missing) console.log(`MISSING ${f}`);
+if (missing.length) {
+  console.error(
+    `\n${missing.length} file(s) the build needs are absent from the published package.` +
+      `\nThis does not fail a build or a test — it fails silently for whoever installs it.`,
+  );
+  process.exit(1);
+}
+console.log('ok — every build input ships');

package/scripts/smoke.mjs

@@ -0,0 +1,76 @@
+// End-to-end smoke test: speaks JSON-RPC to `simframe mcp` over stdio.
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.js');
+const child = spawn(process.execPath, [CLI, 'mcp'], { stdio: ['pipe', 'pipe', 'inherit'] });
+
+let buf = '';
+const pending = new Map();
+child.stdout.on('data', (d) => {
+  buf += d;
+  let i;
+  while ((i = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, i).trim();
+    buf = buf.slice(i + 1);
+    if (!line) continue;
+    const msg = JSON.parse(line);
+    if (msg.id && pending.has(msg.id)) {
+      pending.get(msg.id)(msg);
+      pending.delete(msg.id);
+    }
+  }
+});
+
+let nextId = 1;
+function send(method, params) {
+  const id = nextId++;
+  return new Promise((resolve) => {
+    pending.set(id, resolve);
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+  });
+}
+function notify(method, params) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method, params })}\n`);
+}
+
+const summarize = (res) =>
+  (res.result?.content || []).map((c) =>
+    c.type === 'image' ? `[image ${Math.round(c.data.length * 0.75 / 1024)}KB]` : c.text,
+  );
+
+const init = await send('initialize', {
+  protocolVersion: '2024-11-05',
+  capabilities: {},
+  clientInfo: { name: 'smoke', version: '0' },
+});
+console.log('initialize ->', init.result.serverInfo);
+notify('notifications/initialized');
+
+const tools = await send('tools/list', {});
+console.log('tools ->', tools.result.tools.map((t) => t.name).join(', '));
+
+for (const [name, args] of [
+  ['sim_devices', {}],
+  ['sim_state', {}],
+  ['sim_look', { detail: 'low' }],
+  ['sim_strip', { count: 4 }],
+  ['sim_recall', { action: 'timeline' }],
+  ['sim_recall', { action: 'at', msAgo: 8000 }],
+  ['sim_capture', { action: 'status' }],
+]) {
+  const t0 = Date.now();
+  const res = await send('tools/call', { name, arguments: args });
+  console.log(`\n--- ${name} (${Date.now() - t0}ms)${res.result?.isError ? ' ERROR' : ''}`);
+  console.log(summarize(res).join('\n'));
+}
+
+const t0 = Date.now();
+const w = await send('tools/call', {
+  name: 'sim_wait',
+  arguments: { mode: 'stable', stableMs: 400, timeoutMs: 5000, includeImage: false },
+});
+console.log(`\n--- sim_wait (${Date.now() - t0}ms)\n${summarize(w).join('\n')}`);
+
+child.kill();

package/scripts/verify-baseline.mjs

@@ -0,0 +1,65 @@
+// Proves the agent-facing flow: look, act, ask again — and get a true answer
+// without threading any baseline through by hand.
+import { spawn, execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UDID = process.argv[2];
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'cli.js');
+const child = spawn(process.execPath, [CLI, 'mcp'], { stdio: ['pipe', 'pipe', 'inherit'] });
+
+let buf = '';
+const pending = new Map();
+child.stdout.on('data', (d) => {
+  buf += d;
+  let i;
+  while ((i = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, i).trim();
+    buf = buf.slice(i + 1);
+    if (line) {
+      const m = JSON.parse(line);
+      if (pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id); }
+    }
+  }
+});
+let id = 1;
+const send = (method, params) => new Promise((r) => {
+  const i = id++;
+  pending.set(i, r);
+  child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: i, method, params })}\n`);
+});
+const call = async (name, args = {}) => {
+  const t0 = Date.now();
+  const r = await send('tools/call', { name, arguments: args });
+  const txt = (r.result?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+  const imgs = (r.result?.content || []).filter((c) => c.type === 'image').length;
+  return { ms: Date.now() - t0, txt, imgs };
+};
+const launch = (bundle) => execFileSync('xcrun', ['simctl', 'launch', UDID, bundle], { stdio: 'ignore' });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+await send('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'v', version: '0' } });
+child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
+
+launch('com.apple.springboard'); await sleep(1500);
+
+console.log('--- 1. agent looks at the screen (implicitly sets its baseline)');
+let r = await call('sim_look', { detail: 'low' });
+console.log(`   ${r.ms}ms, ${r.imgs} image\n   ${r.txt.split('\n').join('\n   ')}`);
+
+console.log('\n--- 2. agent acts, then waits (no baseline passed by hand)');
+launch('com.apple.Preferences');
+r = await call('sim_wait', { includeImage: false, stableMs: 700 });
+console.log(`   ${r.ms}ms\n   ${r.txt.split('\n').join('\n   ')}`);
+
+console.log('\n--- 3. agent polls in text, seconds later — the peer\'s failing case');
+await sleep(2500);
+r = await call('sim_state');
+console.log(`   ${r.ms}ms, ${r.imgs} images\n   ${r.txt.split('\n').join('\n   ')}`);
+
+console.log('\n--- 4. nothing happens; asking again must say so');
+await sleep(1200);
+r = await call('sim_state');
+console.log(`   ${r.ms}ms\n   ${r.txt.split('\n').join('\n   ')}`);
+
+child.kill();

package/src/actions.js

@@ -3,6 +3,7 @@
 // Waiting uses a baseline captured BEFORE each action, which is the whole
 // reason these scripts are reliable rather than racy.
 import * as api from './index.js';
+import * as graph from './graph.js';
 import * as input from './input.js';
 import * as intent from './intent.js';
 import { launchApp, openUrl, setPasteboard, terminateApp } from './simctl.js';
@@ -24,12 +25,32 @@ export function normalizeStep(raw) {
   // Siblings like timeoutMs sit alongside the shorthand key and must survive.
   const { [key]: value, ...rest } = raw;
   const inline = value && typeof value === 'object' && !Array.isArray(value) ? value : { value };
-  return { ...rest, ...inline, action: key };
+  const step = { ...rest, ...inline, action: key };
+  // Drop keys that are present but undefined. `simframe tap X` used to pass
+  // `index: undefined`, which survived here and then crashed the signature
+  // builder before the tap was ever sent.
+  for (const k of Object.keys(step)) if (step[k] === undefined) delete step[k];
+  return step;
 }
 
 export async function runScript(
   deviceQuery,
-  { steps, autoSettle = true, stableMs = 500, timeoutMs = 8000, continueOnError = false, options } = {},
+  {
+    steps,
+    autoSettle = true,
+    stableMs = 500,
+    timeoutMs = 8000,
+    confirmNovel = true,
+    continueOnError = false,
+    // Check each action against what it did last time, and remember what it
+    // does this time. On by default: a flow that cannot tell a wrong turn from
+    // a right one is worse than no flow.
+    verify = true,
+    // Stop when a verified step lands somewhere it should not have. A flow
+    // continuing past a wrong turn taps controls on a screen nobody intended.
+    stopOnUnexpected = true,
+    options,
+  } = {},
 ) {
   if (!Array.isArray(steps) || !steps.length) throw new Error('a script needs at least one step');
   const { device } = await api.ensureDaemon(deviceQuery, options);
@@ -38,7 +59,11 @@ export async function runScript(
 
   const needsInput = steps.some((s) => ACTION_STEPS.has(normalizeStep(s).action));
   if (needsInput) {
-    const driver = await input.detectDriver();
+    // driverFor, not detectDriver: detectDriver asks specifically whether idb
+    // is installed, so every batch flow demanded idb even on a machine where
+    // the daemon was doing the input perfectly well. Single-step `simframe tap`
+    // already went through driverFor, so `tap` worked and `do` did not.
+    const driver = await input.driverFor(udid);
     if (!driver.available) throw new Error(driver.reason);
   }
 
@@ -48,12 +73,25 @@ export async function runScript(
   const results = [];
   const frames = [];
   let failed = false;
+  let carriedScreen = null;
 
   for (const [i, raw] of steps.entries()) {
     const step = normalizeStep(raw);
     const stepStart = Date.now();
     // The baseline for "did the screen react" must predate the action itself.
-    const before = (await api.getState(deviceQuery, { options })).state.hash;
+    const beforeState = (await api.getState(deviceQuery, { options })).state;
+    const before = beforeState.hash;
+    // Identity is structural: a list with new rows is the same screen, and the
+    // pixel hash cannot say so.
+    // The screen this step starts on is the screen the last one ended on —
+    // nothing happens in between. Recomputing it cost a full perception pass
+    // per step for an answer already in hand.
+    const beforeScreen = verify
+      ? (carriedScreen ?? await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs, confirmNovel }))
+      : null;
+    carriedScreen = 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 {
       const detail = await runStep(deviceQuery, udid, step, { screen, options, frames });
       let settled = null;
@@ -73,15 +111,51 @@ export async function runScript(
           noVisibleChange: Boolean(w.noVisibleChange),
         };
       }
+      // Verify against what was predicted, and remember what actually
+      // happened. Without this a step that moved the screen the wrong way
+      // reports success, and the flow carries on believing it worked.
+      let verification = null;
+      if (verify && ACTION_STEPS.has(step.action) && beforeScreen?.hash) {
+        const afterState = (await api.getState(deviceQuery, { options })).state;
+        const kind = afterState.transition?.kind;
+        const afterScreen = await api.screenIdentity(deviceQuery, { options, settleMs: stableMs, timeoutMs, confirmNovel });
+        verification = {
+          ...graph.verdict({ udid, prediction, before: beforeScreen.hash, after: afterScreen.hash, kind }),
+          predicted: prediction ? { to: prediction.to.slice(0, 10), kind: prediction.kind, seen: prediction.count } : null,
+          observed: { to: afterScreen.hash?.slice(0, 10), kind },
+        };
+        // Only remember what was seen on a settled screen: an edge recorded
+        // mid-transition points at a screen that never really existed.
+        // `confirmed` already means the fingerprint held still across two
+        // independent readings, which is the thing `settled` was standing in
+        // for. Requiring both meant a screen that settled slowly recorded
+        // nothing at all.
+        if (afterScreen.confirmed && afterScreen.hash) {
+          graph.record(udid, { from: beforeScreen, action: step, to: afterScreen, kind });
+          carriedScreen = afterScreen;
+        }
+      }
+
+      // Only an unexpected *screen* stops a flow. `unexpected-transition` is no
+      // longer a verdict at all — a noisy classifier disagreeing about whether
+      // a tab switch was a push or a pop is not a reason to call a correct
+      // navigation wrong.
+      const wrongTurn = verification?.verdict === 'unexpected-screen';
       const note = settled?.noVisibleChange ? ' [no visible change]' : '';
       results.push({
         index: i,
         action: step.action,
+        verification,
         ok: true,
         ms: Date.now() - stepStart,
-        detail: `${detail}${note}`,
+        detail: `${detail}${note}${wrongTurn ? ` [${verification.verdict}: ${verification.detail}]` : ''}`,
         settled,
       });
+      if (wrongTurn && stopOnUnexpected && !continueOnError) {
+        results[results.length - 1].ok = false;
+        results[results.length - 1].error = `${verification.verdict}: ${verification.detail}`;
+        break;
+      }
     } catch (err) {
       results.push({ index: i, action: step.action, ok: false, ms: Date.now() - stepStart, error: err.message });
       failed = true;
@@ -91,6 +165,9 @@ export async function runScript(
 
   return {
     device,
+    // Returned so a run that verified end to end can be handed straight to
+    // navigate.saveFlow without the caller reassembling what it just ran.
+    steps,
     results,
     ok: !failed,
     totalMs: Date.now() - startedAt,