simframe 0.12.1 → 0.12.2

package/README.md

@@ -185,6 +185,33 @@ and conditions are in [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md); the judgements
 including a phase cancelled by its own measurement, are in
 [`docs/DECISIONS.md`](docs/DECISIONS.md).
 
+**And the measurements that changed our minds** are in
+[`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md), with what we expected beforehand
+written down beside each — including the capacity comparison the supervisor
+design was assumed to make unnecessary. Asked the same 22 situations, three
+times each:
+
+| arm | accuracy | median | deterministic |
+|---|---|---|---|
+| always the commonest answer | 55% | — | — |
+| **`stillMs > 3000ms`, no model at all** | **95%** | **0 ms** | yes |
+| Apple Foundation Models (~3B, on-device) | 77 / 82 / 86% | ~640 ms | **no** |
+| `qwen3:8b` via Ollama (4-bit, 5.2 GB) | **91%** | 919 ms | yes |
+| `qwen3:14b` via Ollama (4-bit, 9.3 GB) | 82% | 1,489 ms | yes |
+
+Three results, and the third is the one that matters. The larger model scored
+*lower* than the smaller one. A free threshold on a number the daemon already
+computes beat all three, on a population it was never fitted to. And **the
+accuracy ranking inverts the safety ranking**: every arm errs in one direction
+only, Apple's errors are all `wait` where `stop` was right and both Qwen arms'
+are all `stop` where `wait` was right — and a wrong `stop` abandons a plan that
+would have worked, while a wrong `wait` costs a settle. A comparison reporting
+only the percentages would have recommended the wrong model.
+
+The Ollama arm is an **experiment, not a recommendation**: off unless named,
+no weights shipped, no dependency added, and every arm reads the same briefing
+out of `native/supervise.swift` so no arm is answering a different question.
+
 The supervisor's whole vocabulary is three words on purpose. It cannot invent a
 step, skip one, substitute a target or continue past an unexpected screen — not
 because a threshold forbids it but because those are not answers it can give.
@@ -610,6 +637,19 @@ accepted as the name that loop used to have.
   radio button moves ~0.1 % of the screen — below the change threshold — which
   used to burn the full timeout. Now the step returns in ~3 s marked
   `[no visible change]`, so you know to check rather than wait.
+- **And a gesture aimed at a coordinate says what it landed on.** A tap or swipe
+  that changed nothing prints the element covering its start point, because a
+  gesture goes to whatever is on top there:
+
+  ```
+  swiped 83,141 -> 83,800 [no visible change]
+    [the swipe start point 83,141 is inside "Settings" (nav-bar)]
+  ```
+
+  Reported from the field as fifteen minutes lost to six identical swipes that
+  a support banner was swallowing — a banner that was *in the element list the
+  same call printed*. Nothing said "there is something at y≈753 and you started
+  at y=750".
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "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

@@ -491,7 +491,12 @@ const walked = await jsonRetry(['goto', target.hash], { allowFail: true });
 // neither walking there nor naming why it cannot, so this check failed with an
 // empty detail — the reason was `undefined` — and the check was right to fail.
 // Now there is a name for it, and the list has to know the name.
-const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen', 'no-identity'];
+// `route-halted` and `arrived-elsewhere` are new: a walk that ran and did not
+// land used to return `{ok: false}` with no reason at all, which failed this
+// very check with an empty detail. It was the one outcome here nobody had
+// named, and the check found it.
+const outcomes = ['no-route', 'unreplayable-edge', 'ambiguous', 'unknown-screen', 'no-identity',
+  'route-halted', 'arrived-elsewhere'];
 check(walked.ok === true || outcomes.includes(walked.reason),
   'and asked for a screen it knows, it either walks there or names why it cannot',
   walked.ok ? (walked.already ? 'already there' : `walked ${walked.ranSteps} step(s)`) : walked.reason);

package/scripts/collect-rulings.mjs

@@ -310,3 +310,17 @@ if (unattributed) console.log(`\n${unattributed} ruling(s) came from a step this
   }
 }
 console.log(`\nthe log now holds ${all.length} ruling(s) — simframe supervisions --device=${dev.udid}`);
+
+// Close the helper, or this script never exits.
+//
+// The supervisor keeps a warm child process and deliberately does not unref its
+// stdout — unreferencing it once unreferenced the pipe every request waits on,
+// and the process then exited silently mid-await. The consequence nobody had
+// noticed is at *this* end: the script finishes its work, prints this line, and
+// then sits at 0% CPU forever with the helper idle at `readLine`, because the
+// live child is holding the event loop open.
+//
+// That is the whole story of three "orphaned" collect-rulings processes killed
+// by PID the night before, which were attributed to a task runner not killing
+// its children. They had each finished their work and could not leave.
+supervisor.close();

package/scripts/eval-fingerprint.mjs

@@ -129,7 +129,24 @@ for (let round = 1; round <= rounds; round += 1) {
     if (screen.steps?.length) {
       // Verification is off: this measures fingerprints, and a wrong-turn
       // verdict computed from the very tokens under test would be circular.
-      await actions.runScript(device, { steps: screen.steps, verify: false });
+      //
+      // The tour asserts arrival rather than sleeping through it, so a step
+      // here can now fail — `openUrl` returns NSPOSIXErrorDomain 60 on a loaded
+      // hosted runner, and a page that never renders no longer passes silently
+      // as a six-token reading. That is the trade this harness wants: a loud
+      // failure naming the screen, over a quiet one that shows up thirty lines
+      // later as a threshold with no clearance. Everything read so far is
+      // written out first, because a failing run is the one whose evidence
+      // matters.
+      try {
+        await actions.runScript(device, { steps: screen.steps, verify: false });
+      } catch (err) {
+        save({ abandonedAt: { screen: screen.name, round, error: err.message } });
+        console.error(`\nFAIL round ${round}, "${screen.name}" never arrived: ${err.message}`);
+        console.error('The tour waits for something each screen actually shows. This is that wait');
+        console.error('giving up — not a fingerprint result. Check the app, the network, or the runner.');
+        process.exit(1);
+      }
     }
     const id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
     // Did we actually arrive? Two differently-named screens reading the same
@@ -339,7 +356,16 @@ console.log(`${thresholdInGap ? 'ok  ' : 'WARN'} the threshold ${thresholdInGap
 const worstSame = [...same].sort((a, b) => a.similarity - b.similarity)[0];
 const worstDifferent = [...different].sort((a, b) => b.similarity - a.similarity)[0];
 if (worstSame) {
-  console.log(`\nweakest same-screen pair:   ${worstSame.a.name} r${worstSame.a.round} vs r${worstSame.b.round} = ${f(worstSame.similarity)} (${worstSame.a.count} vs ${worstSame.b.count} tokens)`);
+  // Say whether either side was read off a screen that was still moving.
+  //
+  // The counts have always been printed and the settle flag never was, so a red
+  // run showing `11 vs 6 tokens` left it open whether the fingerprint had
+  // drifted or one reading had simply been taken too early. It is printed per
+  // reading above, thirty lines away and on a different row; here it is beside
+  // the number it explains.
+  const moving = [worstSame.a, worstSame.b].filter((r) => r.settled === false).length;
+  const movingNote = moving ? `, ${moving === 2 ? 'both readings' : 'one reading'} taken on a screen that never settled` : '';
+  console.log(`\nweakest same-screen pair:   ${worstSame.a.name} r${worstSame.a.round} vs r${worstSame.b.round} = ${f(worstSame.similarity)} (${worstSame.a.count} vs ${worstSame.b.count} tokens${movingNote})`);
 }
 if (worstDifferent) {
   console.log(`closest different-screen pair: ${worstDifferent.a.name} vs ${worstDifferent.b.name} = ${f(worstDifferent.similarity)}`);

package/scripts/replay-rulings.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Ask several supervisors the same questions.
+//
+//   node scripts/replay-rulings.mjs --device=<udid> --arms=apple,ollama:qwen3:8b,ollama:qwen3:14b
+//
+// The owner's call, 2026-09-11: settle the capacity question with numbers
+// rather than speculation. This is how, and the shape matters more than the
+// result.
+//
+// **Why replay rather than re-drive.** Collecting a population per arm means
+// driving the simulator once per arm — about half an hour each — and, worse, it
+// puts the *device's* variance inside a comparison that is supposed to be about
+// the judges. A list that happened to arrive faster on one pass than another is
+// not a fact about a model. So one device pass records the situations (see
+// `situation` in metrics.recordSupervision) and every arm answers the identical
+// set.
+//
+// **What replay cannot measure**, stated here rather than discovered later: the
+// `outcome` column. Whether acting on a ruling actually recovered the flow is a
+// fact about the device at that moment, and it belongs to the arm that was
+// live. Replay scores *decisions*. The distinction is load-bearing — the live
+// population scored 91% by decision and 69% by outcome, and almost all of that
+// gap was one fixture that took the right word eight times and recovered once.
+import * as metrics from '../src/metrics.js';
+import * as ollama from '../src/ollama.js';
+import * as supervisor from '../src/supervisor.js';
+import { resolveDevice } from '../src/platform/index.js';
+
+const arg = (n, d) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${n}=`));
+  return hit ? hit.slice(n.length + 3) : d;
+};
+
+/** The fixtures and the word each situation actually calls for. Same table as the scorer. */
+const CORRECT = {
+  'the list is still loading; its rows arrive shortly after launch': 'wait',
+  'the detail screen is still fetching; its text arrives shortly': 'wait',
+  'the list arrives in waves and this row is in the last one': 'wait',
+  'Review is blocked until Species is filled in, and it is empty': 'stop',
+  'the first submit always fails and the second works, so waiting cannot help': 'stop',
+};
+
+/** `retry` and `wait` differ only in how long they settle, so both satisfy a wait. */
+const satisfies = (d, want) => (want === 'wait' ? d === 'wait' || d === 'retry' : d === want);
+
+const dev = await resolveDevice(arg('device'));
+const arms = String(arg('arms', 'apple')).split(',').map((a) => a.trim()).filter(Boolean);
+const lastN = Number(arg('last', 0));
+
+const all = metrics.readSupervisions(dev.udid)
+  .filter((r) => CORRECT[r.expect] && r.situation?.step && r.situation?.failure);
+const rows = lastN > 0 ? all.slice(-lastN) : all;
+
+if (rows.length < 8) {
+  console.error(`only ${rows.length} replayable ruling(s) — need situations recorded, which`);
+  console.error('means a population collected after the situation field was added.');
+  console.error('Run: SIMFRAME_SUPERVISOR=apple node scripts/collect-rulings.mjs --device=<udid>');
+  process.exit(2);
+}
+
+const want = (r) => CORRECT[r.expect];
+const counts = rows.reduce((a, r) => ({ ...a, [want(r)]: (a[want(r)] ?? 0) + 1 }), {});
+const commonest = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+const baseline = commonest[1] / rows.length;
+const pct = (x) => `${(100 * x).toFixed(0)}%`;
+
+console.log(`${rows.length} situations from ${dev.name}`);
+console.log(`balance: ${JSON.stringify(counts)}`);
+console.log(`majority-class baseline: always "${commonest[0]}" scores ${pct(baseline)}`);
+if (baseline > 0.65) {
+  console.log('\nSKEWED — any accuracy below is mostly a fact about the fixture set.');
+}
+// The free comparison, computed here so it is in the same table as the models
+// rather than in a different report. It is not an arm; it is the thing every
+// arm has to beat to be worth its latency.
+const STILL_MS_THRESHOLD = 3000;
+console.log(`\nthe brief every model arm gets is ${ollama.readBrief().length} characters, read from native/supervise.swift`);
+
+const results = [];
+for (const arm of arms) {
+  const judged = [];
+  let unanswered = 0;
+  // Weights first, so the first situation is not timing a disk read.
+  if (arm.startsWith('ollama')) await ollama.preload(ollama.parseTarget(arm));
+  process.stdout.write(`\nasking ${arm} …`);
+  for (const r of rows) {
+    const detail = {};
+    const ruling = await supervisor.judge({
+      ...r.situation,
+      options: { supervisor: arm },
+      // Wide on purpose. The shipped budget is 2.5s and a 14B will exceed it;
+      // capping here would score the larger model on *latency* while calling it
+      // accuracy, and latency is reported separately below where it can be read
+      // for what it is.
+      timeoutMs: 30_000,
+      detail,
+    });
+    if (!ruling) unanswered += 1;
+    judged.push({ r, ruling, detail });
+    process.stdout.write('.');
+  }
+  const answered = judged.filter((j) => j.ruling);
+  const right = answered.filter((j) => satisfies(j.ruling.decision, want(j.r))).length;
+  const lat = answered.map((j) => j.ruling.ms).filter(Number.isFinite).sort((a, b) => a - b);
+  results.push({
+    arm,
+    n: rows.length,
+    unanswered,
+    // Scored over every situation, not only the answered ones. A judge that
+    // declines half the questions and is right about the rest is not an 100%
+    // judge, and scoring only its answers would say it was.
+    accuracy: right / rows.length,
+    medianMs: lat.length ? lat[lat.length >> 1] : null,
+    errors: answered
+      .filter((j) => !satisfies(j.ruling.decision, want(j.r)))
+      .map((j) => `said "${j.ruling.decision}" where "${want(j.r)}" was right — ${j.r.expect.slice(0, 48)}`),
+  });
+  process.stdout.write(' done\n');
+}
+
+const stillRule = rows.filter((r) => {
+  const d = (r.situation.stillMs ?? 0) > STILL_MS_THRESHOLD ? 'stop' : 'wait';
+  return satisfies(d, want(r));
+}).length / rows.length;
+
+console.log(`\n${'arm'.padEnd(26)} ${'accuracy'.padStart(9)} ${'median'.padStart(9)} ${'no answer'.padStart(10)}`);
+console.log('-'.repeat(58));
+console.log(`${`always "${commonest[0]}"`.padEnd(26)} ${pct(baseline).padStart(9)} ${'—'.padStart(9)} ${'—'.padStart(10)}`);
+console.log(`${`stillMs > ${STILL_MS_THRESHOLD}ms`.padEnd(26)} ${pct(stillRule).padStart(9)} ${'0ms'.padStart(9)} ${'—'.padStart(10)}`);
+for (const r of results) {
+  console.log(`${r.arm.padEnd(26)} ${pct(r.accuracy).padStart(9)} ${`${r.medianMs ?? '—'}ms`.padStart(9)} ${`${r.unanswered}`.padStart(10)}`);
+}
+
+console.log('\nerrors, by arm:');
+for (const r of results) {
+  console.log(`  ${r.arm}`);
+  if (!r.errors.length) console.log('    none');
+  const seen = new Map();
+  for (const e of r.errors) seen.set(e, (seen.get(e) ?? 0) + 1);
+  for (const [e, n] of [...seen].sort((a, b) => b[1] - a[1])) console.log(`    ${String(n).padStart(3)}x ${e}`);
+}
+
+console.log('\nThis scores DECISIONS on identical inputs. It cannot score outcomes —');
+console.log('whether acting on a ruling recovered the flow is a fact about the device at');
+console.log('that moment, and belongs to whichever arm was live. See docs/EXPERIMENTS.md.');
+
+supervisor.close();

package/scripts/score-rulings.mjs

@@ -42,7 +42,25 @@ const all = metrics.readSupervisions(dev.udid).filter((r) => CORRECT[r.expect]);
 // test was 16/16. Mixing a known-bad population into the denominator is the
 // same error as before wearing a different hat.
 const lastN = Number(arg('last', 0));
-const rows = lastN > 0 ? all.slice(-lastN) : all;
+// Which judge. Every arm of the capacity comparison writes to one log, so
+// scoring without this would average a 3B, an 8B and a 14B into a single
+// meaningless number — and it would look like a result.
+const arm = arg('arm', null);
+const armOf = (r) => r.supervisor ?? 'unrecorded';
+const scoped = arm ? all.filter((r) => armOf(r) === arm) : all;
+const rows = lastN > 0 ? scoped.slice(-lastN) : scoped;
+
+// A population spanning several arms is not one population. Say so, and say
+// what to pass, rather than printing an average of things that were never
+// comparable.
+const arms = [...new Set(rows.map(armOf))];
+if (arms.length > 1) {
+  console.log(`this log holds rulings from ${arms.length} supervisor arms:`);
+  for (const a of arms) console.log(`  ${String(rows.filter((r) => armOf(r) === a).length).padStart(4)}  ${a}`);
+  console.log('\nScore one at a time — `--arm=<name>` — because averaging them is not a result.');
+  process.exit(2);
+}
+if (rows.length) console.log(`arm: ${arms[0]}\n`);
 if (rows.length < 8) {
   console.error(`only ${rows.length} labelled ruling(s) — run scripts/collect-rulings.mjs first`);
   process.exit(2);

package/src/actions.js

@@ -260,6 +260,8 @@ export async function runScript(
         expect,
         failure,
         outcome,
+        supervisor: supervisor.requested(options),
+        situation: ruling?.context?.situation ?? null,
       });
     } catch {
       /* instrumentation must not be able to fail a flow it is only watching */
@@ -354,12 +356,19 @@ export async function runScript(
         }),
         observedMs: null,
       };
+      // Where the hands actually went, filled in by the step that moved them.
+      //
+      // Item 120 needs the *resolved* point, not the one in the script: an
+      // image-space `tapAt` is converted inside the step, and `scroll` invents
+      // its coordinates from the screen size. Reading them back off the step
+      // would diagnose a point nothing was ever aimed at.
+      const aim = { at: null };
       let detail;
       // A selector that did not resolve gets the step's own alternatives before
       // the batch is abandoned. Anything else propagates: retrying from a screen
       // we did not expect to be on is not a retry, it is a second guess.
       try {
-        detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+        detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim });
       } catch (thrown) {
         let err = thrown;
         // Ask the supervisor before anything is abandoned. It sits behind the
@@ -393,7 +402,7 @@ export async function runScript(
             options,
           }).catch(() => null);
           try {
-            detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus });
+            detail = await runStep(deviceQuery, udid, step, { screen, options, frames, focus, aim });
             detail += ` [the local supervisor said ${ruling.decision}; it worked on the second attempt]`;
             ruled('recovered');
             continue;
@@ -433,7 +442,7 @@ export async function runScript(
         let last = err;
         for (const label of allowed) {
           try {
-            detail = await runStep(deviceQuery, udid, stepWithTarget(step, label), { screen, options, frames, focus });
+            detail = await runStep(deviceQuery, udid, stepWithTarget(step, label), { screen, options, frames, focus, aim });
             detail += ` [after ${tried.map((t) => JSON.stringify(String(t))).join(', ')} did not resolve]`;
             last = null;
             break;
@@ -729,10 +738,40 @@ export async function runScript(
         ? ' [the screen did not change, so this app was already in front — or it did not come forward]'
         : '';
       const filling = stillFillingIn(afterReading?.entry);
+      // Item 120: when a gesture aimed at a coordinate does nothing, say what
+      // that coordinate resolved to. The element that swallowed it is normally
+      // already in the list printed under this very verdict — the gap was
+      // never the data, it was that nobody connected "started at y=750" to
+      // "there is a banner at y=753".
+      //
+      // Diagnosed against the screen as it was *before* the action, because
+      // that is the screen the finger landed on. Using the after-reading would
+      // describe the world the gesture failed to change.
+      // Both signals, because they are not the same one and only one of them
+      // fires in the reported case. `settled.noVisibleChange` is the pixel
+      // detector saying the frame never moved; the `no-visible-change` verdict
+      // is the fingerprint saying we are on the screen we started on. A swipe
+      // into a search bar settled in 62ms and produced the second without the
+      // first — and six swipes reporting "no visible change" is what item 120
+      // was reported against. Keying on one of them would have shipped a fix
+      // that did not fire on its own bug report.
+      const wentNowhere = Boolean(settled?.noVisibleChange) || verification?.verdict === 'no-visible-change';
+      const aimNote = wentNowhere && aim.at
+        ? screenmap.describePoint(
+          // `beforeScreen` is null with verification off, and that is exactly
+          // the mode someone falls back to when coordinates are misbehaving.
+          // A stored map keyed on the pre-action frame costs one file read.
+          beforeScreen?.entry ?? screenmap.recall(udid, before),
+          aim.at.point,
+          { what: aim.at.what },
+        )
+        : null;
       const note = launchNote
         + (filling ? ` [settled, but ${filling} — waitFor content, do not act on this yet]` : '')
         + (settled?.smallChange ? ' [a small change, in one region only]' : '')
         + (settled?.noVisibleChange ? ' [no visible change]' : '')
+        // After the symptom, because it is the explanation of it.
+        + (aimNote ? ` [${aimNote}]` : '')
         + (settled?.staleBaseline ? ' [baseline had already settled; re-taken from the live screen]' : '')
         + (settled?.blackFrames
           ? ` [${settled.blackFrames} black frame(s) waited through${settled.blackMs ? `, still black after ${settled.blackMs}ms` : ''}]`
@@ -1215,17 +1254,25 @@ async function superviseFailure(deviceQuery, { goal, step, expected, err, option
     try {
       timing = udid && map.identity ? graph.timingFor(udid, map.identity, step) : null;
     } catch { /* an unknown edge is a fact about the graph, not a failure here */ }
-    const ruling = await supervisor.judge({
-      goal,
+    // The question, kept — not just the answer.
+    //
+    // Three items (101, 96, 106) want to ask "what would a different judge have
+    // said about these same situations", and until now the log held the verdict
+    // and threw away what was asked. So comparing two supervisors meant driving
+    // the device once per arm, which is thirty minutes an arm and introduces
+    // the device's own variance into a comparison that is supposed to be about
+    // the judges. With this, one device pass produces a population every arm
+    // can be asked, on identical inputs.
+    const situation = {
+      goal: goal ?? null,
       step: `${step.action} ${JSON.stringify(String(step.value ?? step.target ?? step.into ?? step.seek ?? '').slice(0, 60))}`,
-      expected,
+      expected: expected ?? null,
       failure: err.message,
       screen: (map.rows ?? []).filter((r) => r.label).map((r) => r.label),
       stillMs,
       note: stillFillingIn(map.identity?.entry),
-      options,
-      detail,
-    });
+    };
+    const ruling = await supervisor.judge({ ...situation, options, detail });
     if (!ruling) return null;
     return {
       ...ruling,
@@ -1237,6 +1284,7 @@ async function superviseFailure(deviceQuery, { goal, step, expected, err, option
         stillMs,
         p95: timing?.p95 ?? null,
         samples: timing?.samples ?? null,
+        situation,
       },
     };
   } catch {
@@ -2166,6 +2214,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
           pointHeight: geo.pointHeight,
         }));
       }
+      if (ctx.aim) ctx.aim.at = { point: { x, y }, what: 'the tap point' };
       await input.tapPoint(udid, x, y, { durationMs: step.durationMs });
       return `tapped ${x},${y}`;
     }
@@ -2253,6 +2302,9 @@ async function runStep(deviceQuery, udid, step, ctx) {
     case 'swipe': {
       const from = { x: step.from?.[0] ?? step.from?.x, y: step.from?.[1] ?? step.from?.y };
       const to = { x: step.to?.[0] ?? step.to?.x, y: step.to?.[1] ?? step.to?.y };
+      // The start point only. A swipe is captured by whatever the finger goes
+      // down on; where it lifts never decides who received it.
+      if (ctx.aim) ctx.aim.at = { point: from, what: 'the swipe start point' };
       await input.swipe(udid, from, to, { durationMs: step.durationMs });
       return `swiped ${from.x},${from.y} -> ${to.x},${to.y}`;
     }
@@ -2269,6 +2321,7 @@ async function runStep(deviceQuery, udid, step, ctx) {
         right: [{ x: midX - span, y: midY }, { x: midX + span, y: midY }],
       };
       if (!moves[dir]) throw new Error(`unknown scroll direction "${dir}"`);
+      if (ctx.aim) ctx.aim.at = { point: moves[dir][0], what: 'the scroll start point' };
       await input.swipe(udid, moves[dir][0], moves[dir][1], { durationMs: step.durationMs ?? 250 });
       return `scrolled ${dir}`;
     }

package/src/cli.js

@@ -278,6 +278,10 @@ async function main() {
   if (flags.sensor) options.sensor = String(flags.sensor);
   if (flags.planner) options.planner = String(flags.planner);
   if (flags.supervisor) options.supervisor = String(flags.supervisor);
+  // Stated rather than defaulted, which is the same rule the settle budgets
+  // follow. The default is sized on a developer's machine; a loaded build farm
+  // is a different machine and should say so rather than be guessed at.
+  if (flags.readyTimeoutMs) options.readyTimeoutMs = num(flags.readyTimeoutMs);
 
   switch (command) {
     case undefined:
@@ -734,12 +738,25 @@ async function main() {
           `"${target}" matches more than one screen:`,
           ...(res.candidates ?? []).map((c) => `  ${c.name}  (${c.hash.slice(0, 8)})`),
         ],
+        // Both of these walked, so the steps they took are the useful part and
+        // are printed exactly as a flow prints them.
+        'route-halted': () => [
+          ...(res.results ?? []).map(stepLine),
+          `stopped after ${res.ranSteps} of ${res.steps?.length} step(s) on the way to ${res.screen}`,
+        ],
+        'arrived-elsewhere': () => [
+          ...(res.results ?? []).map(stepLine),
+          `ended at ${res.arrived}, wanted ${res.screen} — every step ran, so an edge the graph`
+            + ' remembers no longer leads where it says. Re-walk it and the graph will relearn.',
+        ],
       };
       if (!res.ok && res.reason) {
         emit(flags, res, refusal[res.reason] ?? `${res.reason}: cannot reach "${res.to ?? target}" from here`);
         process.exitCode = 1;
         return;
       }
+      // Everything that is not ok now carries a reason and was handled above,
+      // so this is the arrival path only.
       emit(
         flags,
         res,
@@ -747,9 +764,7 @@ async function main() {
           ? `already on ${res.screen}`
           : [
               ...(res.results ?? []).map(stepLine),
-              res.ok
-                ? `arrived at ${res.screen} in ${res.ranSteps} step(s)`
-                : `ended at ${res.arrived}, wanted ${res.screen}`,
+              `arrived at ${res.screen} in ${res.ranSteps} step(s)`,
             ],
       );
       process.exitCode = res.ok ? 0 : 1;
@@ -841,11 +856,15 @@ async function main() {
         /* capture not running: fall through and report the send alone */
       }
       const t0 = Date.now();
+      // Item 120, the single-shot half: a coordinate that changed nothing owes
+      // an answer about what it landed on.
+      let aim = null;
       switch (command) {
         case 'tapAt': {
           if (positional.length < 2 || nums.slice(0, 2).some(Number.isNaN)) {
             throw new Error('usage: simframe tapAt <x> <y>');
           }
+          aim = { point: { x: nums[0], y: nums[1] }, what: 'the tap point' };
           await input.tapPoint(dev.udid, nums[0], nums[1], flags.durationMs ? { durationMs: num(flags.durationMs) } : {});
           break;
         }
@@ -853,6 +872,7 @@ async function main() {
           if (positional.length < 4 || nums.slice(0, 4).some(Number.isNaN)) {
             throw new Error('usage: simframe swipe <x1> <y1> <x2> <y2>');
           }
+          aim = { point: { x: nums[0], y: nums[1] }, what: 'the swipe start point' };
           await input.swipe(dev.udid, { x: nums[0], y: nums[1] }, { x: nums[2], y: nums[3] }, { durationMs: num(flags.durationMs, 300) });
           break;
         }
@@ -886,14 +906,22 @@ async function main() {
       // Deliberately not an accusation. Pressing home while already on the
       // springboard legitimately changes nothing, and a warning that cries wolf
       // is how a real one gets ignored.
+      // The map for the screen as it was before the send. Free when the screen
+      // has been perceived once — and silent when it has not, because "we did
+      // not look" must not be printed as "there is nothing there".
+      const hit = changed === false && aim
+        ? api.screenmap.describePoint(api.screenmap.recall(dev.udid, before), aim.point, { what: aim.what })
+        : null;
       const note = changed === false
-        ? ' — the screen did not change. That is expected if the press had nothing to do here;'
+        ? ' — the screen did not change'
+          + (hit ? `, and ${hit}` : '')
+          + '. That is expected if the press had nothing to do here;'
           + ' if you expected a change, input may not be reaching the device —'
           + ' `simframe stop --force && simframe start` rebuilds the session.'
         : '';
       emit(
         flags,
-        { ok: true, command, ms, driver: driver.name, screenChanged: changed },
+        { ok: true, command, ms, driver: driver.name, screenChanged: changed, hit: hit ?? undefined },
         `${command} in ${ms}ms via ${driver.name}${changed === true ? ' — screen changed' : ''}${note}`,
       );
       return;

package/src/index.js

@@ -110,6 +110,21 @@ async function deviceGeometry(udid, state) {
   };
 }
 
+/**
+ * How long to wait for a daemon to exist at all. A first build is slower than a
+ * spawn, which is what this number is sized for.
+ */
+export const READY_TIMEOUT_MS = 20_000;
+
+/**
+ * How long to keep waiting once the daemon is demonstrably alive.
+ *
+ * Sized from the measurement that caused it: a hosted runner's simulator took
+ * roughly 27 s to produce its first frame while the daemon reported a healthy
+ * 75 ms median. Three times the ordinary budget, and still bounded.
+ */
+export const LIVE_DAEMON_CAP_MS = 60_000;
+
 export function daemonStatus(udid) {
   const meta = store.readJson(store.paths(udid).meta);
   const pid = meta?.pid ?? null;
@@ -146,16 +161,40 @@ export async function ensureDaemon(deviceQuery, options = {}) {
   }
 
   // The daemon may need a first build, which is slower than a spawn.
-  const deadline = Date.now() + (options.readyTimeoutMs ?? 20_000);
-  while (Date.now() < deadline) {
+  const deadline = Date.now() + (options.readyTimeoutMs ?? READY_TIMEOUT_MS);
+  // A live daemon that has not rendered yet is not a failed daemon.
+  //
+  // Measured on a hosted runner: `simframe start` gave up, and the daemon's own
+  // log — captured by the on-failure step eight seconds later — showed
+  // `frame=#1 age=1514ms, 1.0 fps, median 75.08ms`. It was working. The
+  // simulator's display had simply taken about 27 s to produce anything on a
+  // loaded build farm, against a 20 s budget measured on a developer's machine.
+  // Aborting there fails an entire run over a device that was about to work.
+  //
+  // So the budget applies to *getting a daemon*; once we have a live one, the
+  // wait extends to a hard cap. The cap still exists, because a daemon that is
+  // alive and never renders is a real failure and has to be reportable — but it
+  // is now a different sentence from a daemon that never started, and those two
+  // had read identically, which cost a log dive to tell apart.
+  const liveDeadline = Date.now() + LIVE_DAEMON_CAP_MS;
+  let sawLiveDaemon = false;
+  for (;;) {
     const state = store.readJson(p.state);
     if (state && state.capturedAt >= minCapturedAt && Date.now() - state.capturedAt < 30_000) {
       return { device, state, started: !existing.alive };
     }
+    const alive = daemonStatus(device.udid).alive;
+    sawLiveDaemon = sawLiveDaemon || alive;
+    if (Date.now() >= (alive ? liveDeadline : deadline)) break;
     await sleep(80);
   }
   const tail = readLogTail(p.log);
-  throw new Error(`simframe daemon did not produce a frame for ${device.name}${tail ? `\n${tail}` : ''}`);
+  const waited = sawLiveDaemon
+    ? `the daemon is running and the display produced no frame in ${Math.round(LIVE_DAEMON_CAP_MS / 1000)}s`
+    : 'no daemon process came up';
+  throw new Error(
+    `simframe daemon did not produce a frame for ${device.name} — ${waited}${tail ? `\n${tail}` : ''}`,
+  );
 }
 
 /** Why the daemon was not used, when it was not. Surfaced by doctor. */

package/src/metrics.js

@@ -151,7 +151,7 @@ export const readSupervisions = (udid, opts) => readJsonl(metricPaths(udid).supe
  */
 export function recordSupervision(udid, {
   session, index, step, edge, screen, decision, from, reason, ms,
-  stillMs, p95, samples, expect, failure, outcome,
+  stillMs, p95, samples, expect, failure, outcome, supervisor, situation,
 }) {
   // Swallowed rather than thrown, unlike `recordEscalation`'s guard, and the
   // difference is deliberate: this is called from inside a flow's failure
@@ -171,6 +171,19 @@ export function recordSupervision(udid, {
     screen_fingerprint: screen ?? null,
     decision,
     from: from ?? 'model',
+    // *Which* judge, not just that there was one.
+    //
+    // Every arm of the capacity comparison writes to this one log, and without
+    // this field a population collected under Apple and one collected under a
+    // 14B are one undifferentiated file — the comparison the owner asked for
+    // would be unreadable from its own data. `from` says rule-or-model; this
+    // says which model.
+    supervisor: supervisor ?? null,
+    // The question, not only the answer. Without it, asking a second judge
+    // about the same situations means driving the device a second time — which
+    // puts the device's own variance inside a comparison that is about the
+    // judges. Null for a rule-sourced ruling, which never composed one.
+    situation: situation ?? null,
     // Recorded, never presented as the ground for what happened: the supervisor
     // has returned a correct decision with a reason citing a rule that did not
     // apply. Keeping it is how that stays measurable instead of anecdotal.
@@ -312,6 +325,11 @@ export const PLAN_REASONS = {
   'no-route': 'no_plan',
   'unreplayable-edge': 'no_plan',
   'unknown-flow': 'no_plan',
+  // A route that ran and did not land. Not `no_plan`: there *was* a plan and it
+  // was followed — what could not be confirmed is that it worked, which is what
+  // `verification_failed` means everywhere else in this file.
+  'route-halted': 'verification_failed',
+  'arrived-elsewhere': 'verification_failed',
 };
 
 /** A short, bounded description of a candidate element, for the log. */

package/src/navigate.js

@@ -96,14 +96,40 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
 
   const result = await runScript(udid, { steps, stopOnUnexpected: true, ...runOptions });
   const arrived = await api.screenIdentity(udid, {});
-  return {
-    ok: arrived.hash === found.node.hash,
+  const walk = {
     screen: found.name,
     steps,
     ranSteps: result.ranSteps,
     results: result.results,
     arrived: arrived.hash ? arrived.hash.slice(0, 8) : null,
   };
+  if (arrived.hash === found.node.hash) return { ok: true, ...walk };
+
+  // A walk that ran and did not land had no name, and it was the only outcome
+  // here that did not.
+  //
+  // Every refusal above is named, logged and groupable; this one returned
+  // `{ok: false}` with no `reason` at all, so `simframe goto <known hash>` on
+  // CI failed the check that says *"it either walks there or names why it
+  // cannot"* with an empty detail — which is exactly what the check is for, and
+  // it had been sitting under an outcome nobody had named rather than under a
+  // crash.
+  //
+  // Two names, because they are two different faults and only one of them is
+  // about the graph. `route-halted` means a step on the route failed, which is
+  // an ordinary failure of the app or the moment. `arrived-elsewhere` means
+  // every step ran and we are *not where the graph promised* — an edge it
+  // remembers is wrong, and that is worth reading as a claim about memory
+  // rather than about this attempt.
+  const reason = !arrived.hash
+    ? 'no-identity'
+    : (result.ranSteps < steps.length ? 'route-halted' : 'arrived-elsewhere');
+  return refuse(udid, { ok: false, reason, to: found.name, ...walk }, {
+    detail: reason === 'arrived-elsewhere'
+      ? `route to "${found.name}" ran to the end and landed on ${walk.arrived}`
+      : `route to "${found.name}" stopped after ${result.ranSteps} of ${steps.length} step(s)`,
+    flowName: `goto:${target}`,
+  });
 }
 
 export function knownScreens(udid) {

package/src/ollama.js

@@ -0,0 +1,204 @@
+/**
+ * A second supervisor arm, for measuring whether capacity matters.
+ *
+ * The owner's call, 2026-09-11: *"we can of course do our own test with a
+ * chosen model… and decide based on the numbers rather than speculations."*
+ * This exists to answer that and nothing else. It is **not** a recommendation,
+ * it is off unless asked for by name, and a model used to measure whether
+ * capacity matters is not a model we ship — conflating those is how a non-goal
+ * erodes.
+ *
+ * No dependency is added: Node has had a global `fetch` since 18, and Ollama
+ * is a process already on the machine, reached over the loopback interface.
+ *
+ * **The fairness condition, which is the whole reason this file is shaped the
+ * way it is.** Most small-model errors are invalid-output faults, and Apple's
+ * guided generation eliminates those at the sampling layer — constraints are
+ * enforced by logit masking, so a fourth word is unrepresentable rather than
+ * rejected afterwards (WWDC25 301; Tech Report §7). An unconstrained challenger
+ * would lose on formatting and we would read it as losing on judgement. So this
+ * arm passes a JSON schema whose `decision` is an enum of the same three words,
+ * and Ollama constrains sampling to it the same way.
+ *
+ * And the briefing is not a second copy. It is **read out of
+ * `native/supervise.swift`**, because two hand-maintained copies of a prompt is
+ * two arms answering different questions, and the difference would be invisible
+ * in the numbers. See `readBrief`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SWIFT = path.join(HERE, '..', 'native', 'supervise.swift');
+
+export const DEFAULT_MODEL = 'qwen3:8b';
+export const DEFAULT_HOST = 'http://127.0.0.1:11434';
+
+/**
+ * The Apple arm's own instructions, read from its source.
+ *
+ * Not duplicated. Two arms of a comparison that are briefed differently are
+ * measuring two different things, and nothing in the output would say so — the
+ * numbers would simply be wrong and look fine. The Swift file is the canonical
+ * copy because it is the shipped one; this parses the `let instructions = """
+ * … """` block out of it and un-escapes Swift's trailing-backslash line
+ * continuations, which is how that literal is wrapped.
+ *
+ * Throws rather than falling back to a built-in string. A silent fallback here
+ * would produce exactly the invisible unfairness this function exists to
+ * prevent.
+ */
+export function readBrief(file = SWIFT) {
+  const src = fs.readFileSync(file, 'utf8');
+  const open = src.indexOf('let instructions = """');
+  if (open === -1) throw new Error(`no instructions block in ${file}`);
+  const bodyStart = src.indexOf('\n', open) + 1;
+  const close = src.indexOf('"""', bodyStart);
+  if (close === -1) throw new Error(`unterminated instructions block in ${file}`);
+  return src
+    .slice(bodyStart, close)
+    .split('\n')
+    // A Swift multi-line literal strips the closing delimiter's indentation
+    // from every line; here that is four spaces.
+    .map((l) => l.replace(/^ {4}/, ''))
+    .join('\n')
+    // Swift's line continuation: a trailing backslash removes the newline and
+    // nothing else. Joining with a space instead would insert one after the
+    // space the line already ends with, and the two arms would be reading
+    // briefs that differ — invisibly, and in the one place this whole file
+    // exists to keep identical.
+    .replace(/\\\n/g, '')
+    .trim();
+}
+
+const clip = (t, n) => {
+  const s = String(t ?? '');
+  return s.length > n ? `${s.slice(0, n)}…` : s;
+};
+
+/**
+ * The situation, in the words the other arm gets.
+ *
+ * A line-for-line mirror of `main.swift`'s prompt assembly, including the clip
+ * lengths and the 14-label cap on the screen list. The field order matters as
+ * much as the content: the brief tells the model to weigh the plan's guidance
+ * first, and a prompt that presented it last would be testing a different
+ * instruction.
+ */
+export function promptFor(s = {}) {
+  let prompt = `Step: ${clip(s.step, 120)}\nIt failed with: ${clip(s.failure, 220)}`;
+  if (s.goal) prompt += `\nThe plan's guidance about this app: ${clip(s.goal, 300)}`;
+  if (s.expected) prompt += `\nExpected: ${clip(s.expected, 200)}`;
+  if (Number.isFinite(s.stillMs)) prompt += `\nThe screen has been still for ${s.stillMs}ms`;
+  if (s.note) prompt += `\nPerception note: ${clip(s.note, 160)}`;
+  if (s.screen?.length) {
+    prompt += `\nOn screen now: ${s.screen.slice(0, 14).map((l) => clip(l, 28)).join(', ')}`;
+  }
+  return prompt;
+}
+
+/**
+ * The schema. Three words and nothing else, enforced at sampling.
+ *
+ * Deliberately decision-only, matching `Judgement` in the Swift file: that
+ * struct has one field. Asking this arm for a rationale it would then be scored
+ * against would be a second difference between the arms, and the rationale is
+ * the one thing a supervisor is explicitly not trusted for.
+ */
+export const SCHEMA = {
+  type: 'object',
+  properties: { decision: { type: 'string', enum: ['wait', 'retry', 'stop'] } },
+  required: ['decision'],
+};
+
+/** Parse `ollama`, `ollama:qwen3:14b`, `ollama:qwen3:8b@http://host:port`. */
+export function parseTarget(raw) {
+  const rest = String(raw ?? '').replace(/^ollama:?/, '');
+  const [model, host] = rest.split('@');
+  return { model: model || DEFAULT_MODEL, host: host || DEFAULT_HOST };
+}
+
+async function post(host, route, body, timeoutMs) {
+  const control = new AbortController();
+  const timer = setTimeout(() => control.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${host}${route}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: control.signal,
+    });
+    if (!res.ok) return { kind: 'http', error: `${res.status} ${await res.text().catch(() => '')}`.slice(0, 200) };
+    return { json: await res.json() };
+  } catch (err) {
+    return { kind: err.name === 'AbortError' ? 'timeout' : 'unreachable', error: String(err.message).slice(0, 200) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * One judgement. Same shape as the Apple helper's answer, so `judge` in
+ * `supervisor.js` cannot tell which arm it asked — including the failure
+ * shapes, because "the supervisor did not answer" covering a timeout, a
+ * refusal and a model that was never installed is a bug this project has
+ * already paid for once.
+ */
+export async function ask(target, situation, timeoutMs = 2500) {
+  const { model, host } = target;
+  const started = Date.now();
+  const out = await post(host, '/api/chat', {
+    model,
+    messages: [
+      { role: 'system', content: readBrief() },
+      { role: 'user', content: promptFor(situation) },
+    ],
+    stream: false,
+    format: SCHEMA,
+    // Qwen3 reasons out loud by default. Turned off for two reasons and both
+    // are about fairness rather than speed: the Apple arm does not deliberate
+    // either, and a supervisor that takes twenty seconds to answer has already
+    // lost the argument it is here to have — it sits in front of a 1.2s budget.
+    think: false,
+    options: { temperature: 0, num_predict: 32 },
+  }, timeoutMs);
+  if (!out.json) return { kind: out.kind, error: out.error };
+  const ms = Date.now() - started;
+  try {
+    return { ...JSON.parse(out.json.message?.content ?? ''), ms };
+  } catch {
+    return { kind: 'unparseable', error: clip(out.json.message?.content, 200), ms };
+  }
+}
+
+/**
+ * Load the weights before timing anything.
+ *
+ * The Apple arm calls `prewarm()` for exactly this reason, and it was worth
+ * ~280ms there. Here it is worth minutes: an 8B at 4-bit is 5.2 GB off disk,
+ * and the first `doctor` probe aborted at 20s and reported a working model as
+ * one that "did not answer" — a cold load reported as a fault. Ollama's
+ * documented preload is a chat with no messages.
+ */
+export async function preload(target, timeoutMs = 120_000) {
+  const { model, host } = target;
+  const started = Date.now();
+  const out = await post(host, '/api/chat', { model, messages: [], keep_alive: '10m' }, timeoutMs);
+  return out.json ? { ok: true, ms: Date.now() - started } : { ok: false, ...out };
+}
+
+/** For `doctor`: is this arm actually there, and does it answer? */
+export async function status(target, timeoutMs = 20_000) {
+  const { model, host } = target;
+  const tags = await post(host, '/api/show', { model }, 4000);
+  if (!tags.json) {
+    return {
+      ok: false,
+      reason: tags.kind === 'unreachable'
+        ? `no Ollama server at ${host} (start it, or pass a host with ollama:<model>@<url>)`
+        : `Ollama has no model "${model}" (${tags.error})`,
+    };
+  }
+  return { ok: true, model, host, timeoutMs };
+}

package/src/screenmap.js

@@ -151,6 +151,82 @@ const inside = (point, frame) =>
   point.y >= frame.y &&
   point.y <= frame.y + frame.height;
 
+const frameArea = (f) => (f ? Math.max(1, f.width) * Math.max(1, f.height) : Infinity);
+
+/**
+ * What the map says is at a point — everything containing it, smallest first.
+ *
+ * Item 120. Six consecutive `swipe [201,750] -> [201,250]` reported
+ * `no visible change` while a support banner sat at y≈753 swallowing every
+ * gesture. The banner was *in the element list the same call printed*; nothing
+ * connected "your swipe started at y=750" to "there is an element at y=753".
+ * The geometry was already in hand, so this is arithmetic over data we hold,
+ * not a new perception pass.
+ *
+ * Smallest first is a deliberately weaker claim than z-order. We do not know
+ * what is on top — the accessibility tree's order is not a paint order and OCR
+ * has none at all — and the honest statement is "these are the elements that
+ * cover that point", innermost first because the innermost is the one a
+ * gesture most often goes to. Saying "overlay" would be a guess wearing the
+ * clothes of a measurement.
+ */
+export function hitTest(entry, point) {
+  if (!entry?.targets || !Number.isFinite(point?.x) || !Number.isFinite(point?.y)) return [];
+  return entry.targets
+    .filter((t) => t.frame && inside(point, t.frame))
+    .sort((a, b) => frameArea(a.frame) - frameArea(b.frame));
+}
+
+const describeTarget = (t) => {
+  const name = t.label || t.text || (t.type ? `(unlabelled ${t.type})` : '(unlabelled)');
+  return t.region ? `"${name}" (${t.region})` : `"${name}"`;
+};
+
+/**
+ * One line saying what a coordinate resolved to, for a gesture that did
+ * nothing visible.
+ *
+ * Returns `null` when there is no map for the screen, because "we did not
+ * look" and "we looked and found nothing" are different answers and only one
+ * of them is worth printing.
+ */
+export function describePoint(entry, point, { what = 'the point' } = {}) {
+  if (!entry?.targets?.length) return null;
+  const at = `${Math.round(point.x)},${Math.round(point.y)}`;
+  const hits = hitTest(entry, point);
+  if (!hits.length) {
+    return `${what} ${at} is not inside any element on the map`
+      + ' — empty space, or a view with no label (nothing can be said about what caught it)';
+  }
+  // The contention clause only where there is contention. On one hit the
+  // element's name *is* the diagnosis and anything after it is noise — and a
+  // note that pads every case is how a real one stops being read.
+  const others = hits.length > 1
+    ? `, the smallest of ${hits.length} elements covering it — a gesture goes to whatever is on top there`
+    : '';
+  return `${what} ${at} is inside ${describeTarget(hits[0])}${others}`;
+}
+
+/**
+ * The point a step is aimed at, when it is aimed at a coordinate at all.
+ *
+ * A swipe is captured by whatever sits under where the finger goes *down*, so
+ * the start point is the one worth diagnosing; the end point never decides who
+ * receives the gesture.
+ */
+export function aimedAt(step) {
+  if (!step) return null;
+  if (step.action === 'tapAt' && Number.isFinite(step.x) && Number.isFinite(step.y)) {
+    return { point: { x: step.x, y: step.y }, what: 'the tap point' };
+  }
+  if (step.action === 'swipe') {
+    const x = step.from?.[0] ?? step.from?.x;
+    const y = step.from?.[1] ?? step.from?.y;
+    if (Number.isFinite(x) && Number.isFinite(y)) return { point: { x, y }, what: 'the swipe start point' };
+  }
+  return null;
+}
+
 /**
  * Build the map for the screen currently showing. Accessibility elements are the
  * real hit targets, so they win where they exist; OCR fills in everything the

package/src/supervisor.js

@@ -33,6 +33,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as store from './store.js';
+import * as ollama from './ollama.js';
 import { compiler, lineServer } from './localhelper.js';
 
 const SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'native', 'supervise.swift');
@@ -45,6 +46,32 @@ const helper = lineServer({
 
 export const DECISIONS = new Set(['wait', 'retry', 'stop']);
 
+/**
+ * Which arm answers.
+ *
+ * Two, and the second one is an experiment rather than a recommendation. The
+ * owner asked for the capacity question to be settled with numbers instead of
+ * speculation, and a comparison needs something to compare against. `apple` is
+ * the shipped arm; `ollama:<model>` asks a local Ollama, off unless named.
+ *
+ * A backend is an object with `ask` and `status` and nothing else, which is the
+ * same shape the platform boundary uses one layer down — so `judge` below
+ * cannot tell which arm it asked, including in the failure shapes.
+ */
+function backendFor(want) {
+  if (want === 'apple') return { kind: 'apple', ask: helper.ask, status: appleStatus };
+  if (want === 'ollama' || want.startsWith('ollama:')) {
+    const target = ollama.parseTarget(want);
+    return {
+      kind: 'ollama',
+      target,
+      ask: (situation, timeoutMs) => ollama.ask(target, situation, timeoutMs),
+      status: () => ollamaStatus(target),
+    };
+  }
+  return null;
+}
+
 /**
  * The vocabulary gate, as a function so it can be *tested* rather than grepped.
  *
@@ -88,9 +115,15 @@ export async function judge({
   goal, step, expected, failure, screen, stillMs, note, options, timeoutMs = 2500,
   detail,
 } = {}) {
-  if (!requested(options)) return null;
+  const want = requested(options);
+  if (!want) return null;
   if (!step || !failure) return null;
-  const answer = await helper.ask({
+  const backend = backendFor(want);
+  if (!backend) {
+    if (detail && typeof detail === 'object') detail.kind = `no such supervisor backend: "${want}"`;
+    return null;
+  }
+  const answer = await backend.ask({
     goal: goal ? String(goal).slice(0, 200) : null,
     step: String(step).slice(0, 200),
     expected: expected ? String(expected).slice(0, 300) : null,
@@ -124,7 +157,59 @@ export async function judge({
 export async function status(options) {
   const want = requested(options);
   if (!want) return { supervisor: 'none', detail: 'not requested (SIMFRAME_SUPERVISOR is unset)' };
-  if (want !== 'apple') return { supervisor: 'none', detail: `no such supervisor backend: "${want}"` };
+  const backend = backendFor(want);
+  if (!backend) return { supervisor: 'none', detail: `no such supervisor backend: "${want}"` };
+  return backend.status();
+}
+
+/**
+ * The experiment arm, reported exactly as honestly as the shipped one.
+ *
+ * Same probe, because "available" from a presence check is the failure this
+ * project has already paid for: the model had stopped answering inside the
+ * long-lived server while `doctor`, in its own process, said it was healthy —
+ * for twenty calls and six failures during which nothing was being judged.
+ *
+ * A wide probe budget on purpose. This arm loads several gigabytes on first
+ * ask, and a cold load timing out would report a working model as broken —
+ * which is a different lie from the one above and just as useless.
+ */
+async function ollamaStatus(target) {
+  const live = await ollama.status(target);
+  if (!live.ok) return { supervisor: 'none', detail: live.reason };
+  // Weights first, then the clock. Without this the probe measured a disk read
+  // and called a working model broken.
+  const warm = await ollama.preload(target);
+  if (!warm.ok) {
+    return {
+      supervisor: 'none',
+      detail: warm.kind === 'timeout'
+        ? `"${target.model}" is still loading after 120s — ask again once it is resident`
+        : `"${target.model}" would not load (${warm.kind}: ${warm.error})`,
+    };
+  }
+  const probe = await ollama.ask(target, {
+    step: 'tap "Probe"',
+    failure: '"Probe" is not on this screen. Visible: Probe',
+    screen: ['Probe'],
+    stillMs: 5000,
+  }, live.timeoutMs);
+  if (decisionOf(probe) == null) {
+    return {
+      supervisor: 'none',
+      detail: `Ollama has "${target.model}" and it did not answer a probe`
+        + `${probe?.kind ? ` (${probe.kind}${probe.error ? `: ${probe.error}` : ''})` : ''}`,
+    };
+  }
+  return {
+    supervisor: `ollama:${target.model}`,
+    detail: `${target.model} via Ollama at ${target.host}; answered a probe in ${probe.ms ?? '?'}ms;`
+      + ' schema-constrained to wait/retry/stop. An experiment arm, not a recommendation —'
+      + ' see docs/EXPERIMENTS.md for what it measured.',
+  };
+}
+
+async function appleStatus() {
   const live = await helper.status();
   if (!live.ok) return { supervisor: 'none', detail: live.reason };
   // Prove a round trip, not a presence.