simframe 0.11.0 → 0.12.1

package/src/index.js

@@ -303,6 +303,18 @@ export const STALE_FRAME_MS = 2500;
  */
 export const MEMORY_SETTLE_MS = 250;
 
+/**
+ * How well a relabelled ref must match before it is acted on.
+ *
+ * Above `matching.MINIMUM_SCORE` (0.45) on purpose: that floor is for a label
+ * the caller wrote, and this is a label simframe substituted after refusing
+ * their `#n`. A fuzzy name match returns `similarity * 0.72` and a prefix match
+ * is scaled by its coverage, so neither can reach 0.8 on the name alone — which
+ * makes this "the label matched nearly exactly", not a tuned constant. The
+ * recovery that made this necessary scored 0.64.
+ */
+export const RELABEL_MIN_SCORE = 0.8;
+
 /** Below this a "change" is a clock digit or a caret, not a new screen. */
 export const MINOR_CHANGE = 0.004;
 export const MAJOR_CHANGE = 0.03;
@@ -1251,6 +1263,35 @@ async function locateWith(
         second.staleLabel = err.staleLabel;
         throw second;
       }
+      // A recovery is held to a higher bar than the lookup it stands in for,
+      // and to one the caller never has to think about.
+      //
+      // `MINIMUM_SCORE` (0.45) is the bar for a label the caller actually
+      // wrote. This label is one *we substituted on their behalf* after
+      // refusing their `#n`, so a weak match here is not "close enough" — it is
+      // us choosing a target nobody named. The reported wrong answer scored
+      // **0.64** and cleared the ordinary floor comfortably.
+      //
+      // 0.8 is structural rather than fitted to that incident: a fuzzy name
+      // match returns `similarity * 0.72` and a prefix match is scaled by its
+      // coverage, so neither reaches 0.8 on the name alone. Only a near-exact
+      // name does. And the region check needs no tuned number at all — if the
+      // map would not offer this target, a recovery may not silently pick it.
+      const region = again.target?.region ?? 'content';
+      const weak = Number.isFinite(again.score) && again.score < RELABEL_MIN_SCORE;
+      if (weak || !regions.offerable(region)) {
+        err.message = `#${selector.ref} cannot be trusted here, and "${err.staleLabel}" was not`
+          + ' safely re-findable either:'
+          + (weak ? ` the best match scored ${again.score.toFixed(2)}, below the ${RELABEL_MIN_SCORE} a`
+            + ' relabel needs (a number you did not ask for may not become a tap on a guess).' : '')
+          + (!regions.offerable(region) ? ` the best match sits in the ${region}, which sim_ui does not`
+            + ' offer as something to act on.' : '')
+          + ' Read the screen again (sim_ui) and name the target.';
+        err.staleRef = true;
+        err.staleLabel = err.staleLabel;
+        err.relabelRefused = { score: again.score ?? null, region };
+        throw err;
+      }
       return {
         ...again,
         from: 'ref-relabelled',

package/src/localhelper.js

@@ -94,7 +94,11 @@ export function lineServer({ ensureBinary, what }) {
           try { msg = JSON.parse(line); } catch { continue; }
           if (!settled) {
             settled = true;
-            if (msg.ready) resolve({ ok: true, child, waiters });
+            // The ready line may carry facts about the helper worth keeping —
+            // the model's context window, for one, which used to be a constant
+            // we repeated in comments. Passed through rather than parsed here,
+            // because this file knows about lines and not about models.
+            if (msg.ready) resolve({ ok: true, child, waiters, hello: msg });
             else resolve({ ok: false, reason: msg.unavailable ?? `the ${what} did not become ready` });
             continue;
           }
@@ -145,7 +149,9 @@ export function lineServer({ ensureBinary, what }) {
     },
     async status() {
       const live = await open();
-      return live?.ok ? { ok: true } : { ok: false, reason: live?.reason ?? 'unavailable' };
+      return live?.ok
+        ? { ok: true, hello: live.hello ?? {} }
+        : { ok: false, reason: live?.reason ?? 'unavailable' };
     },
     close() {
       try { session?.child?.kill(); } catch { /* already gone */ }

package/src/mcp.js

@@ -78,13 +78,22 @@ const deviceProp = {
 };
 
 /**
- * One selector grammar everywhere.
+ * One selector grammar everywhere, and the order is the recommendation.
  *
- * `#3` is the cheapest thing a caller can say and the least ambiguous, because
- * simframe numbered it; a bare phrase is resolved by intent, which is more
- * forgiving and occasionally has to ask which one was meant.
+ * It used to lead with `#3` and call it "cheapest and unambiguous". Four peer
+ * rounds running reported the opposite: intent resolution worked every time,
+ * while refs renumbered underneath them and were only safe inside the round
+ * trip that issued them. The README was corrected and these descriptions were
+ * not, which is the half a caller actually reads.
+ *
+ * "Unambiguous" was also the wrong word for it. A ref is exact about which
+ * element simframe meant and says nothing about whether that element is still
+ * there — the failure mode that needed `staleKind` to tell a moved layout from
+ * a different screen, and then a score floor and a region check on top of that
+ * before a relabelled ref could be trusted. A label carries its own evidence;
+ * a number carries none.
  */
-const SELECTOR = 'Selector: "#3" (a number from the last screen map — cheapest and unambiguous), a label or phrase like "Save" or "the Assets tab" (resolved by intent), or "@120,400" for raw point coordinates.';
+const SELECTOR = 'Selector: a label or phrase like "Save" or "the Assets tab" or "back" (resolved by intent — verbs, typos, synonyms, icon-only controls: START HERE), "#3" (a number from the last screen map — exact, but only inside the round trip that numbered it), or "@120,400" for raw point coordinates (last resort: it cannot tell you it missed).';
 
 const selectorProp = (what = 'What to act on') => ({
   sel: { type: 'string', description: `${what}. ${SELECTOR}` },
@@ -94,7 +103,7 @@ const TOOLS = [
   {
     name: 'sim_ui',
     description:
-      'READ THE SCREEN as text: every element numbered, with region, type, label, state, contents and tap point, plus which screen this is and what simframe knows about it. A tenth the cost of a screenshot and more useful, because it says what is tappable and where. Whatever it calls #3, you can tap as "#3". Start here, never with sim_look.',
+      'READ THE SCREEN as text: every element numbered, with region, type, label, state, contents and tap point, plus which screen this is and what simframe knows about it. A tenth the cost of a screenshot and more useful, because it says what is tappable and where. Act on what it shows by NAME — whatever it calls "General", you can tap as "General"; the #3 numbers are exact but only until the screen moves. Start here, never with sim_look.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -123,7 +132,7 @@ const TOOLS = [
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "#3" | "Save" | "@120,400". 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}}, {"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}}, {"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.',
           items: { type: 'object' },
         },
         autoSettle: {

package/src/metrics.js

@@ -24,6 +24,21 @@ export const REASONS = [
 
 export const OUTCOMES = ['resolved_locally', 'escalated_to_model', 'failed'];
 
+/**
+ * What the executor observed after a supervisor ruling — the field that makes a
+ * ruling scoreable rather than merely recorded.
+ *
+ * A ruling on its own says what the supervisor thought. Three items on the
+ * deferred list (101's p95 replay, 106's cost of the steps a `stop` skipped,
+ * 96's response variable) need what happened *next*, and until now nothing
+ * persisted a ruling at all: they went into a `supervisions` array on the
+ * result and died with the process. Three rulings had ever existed anywhere.
+ *
+ * Closed, and mandatory, for the same reason `REASONS` is: a vocabulary that
+ * admits "other" collects a pile of "other".
+ */
+export const RULING_OUTCOMES = ['recovered', 'still_failed', 'stopped', 'no_ruling'];
+
 /**
  * Which faculty would have removed this escalation.
  *
@@ -57,6 +72,7 @@ function metricPaths(udid) {
     dir,
     escalations: path.join(dir, 'escalations.jsonl'),
     flows: path.join(dir, 'flows.jsonl'),
+    supervisions: path.join(dir, 'supervisions.jsonl'),
     baselines: path.join(dir, 'baselines'),
   };
 }
@@ -109,6 +125,106 @@ export function readJsonl(file, { limit } = {}) {
 
 export const readEscalations = (udid, opts) => readJsonl(metricPaths(udid).escalations, opts);
 export const readFlows = (udid, opts) => readJsonl(metricPaths(udid).flows, opts);
+export const readSupervisions = (udid, opts) => readJsonl(metricPaths(udid).supervisions, opts);
+
+/**
+ * Write down one supervisor ruling and what came of it.
+ *
+ * The fields are chosen so the three items waiting on this can be answered
+ * **offline, from the log**, rather than by another device run:
+ *
+ * - `screen`/`edge` — which `(screen_hash, action)` the ruling was about, so
+ *   rulings can be grouped by edge the way the graph groups timings.
+ * - `p95`/`samples` — what the graph knew about that edge **at the moment of
+ *   the ruling**. Recording it now rather than looking it up later is the
+ *   difference between 101 being arithmetic and 101 being archaeology: the
+ *   graph keeps learning, so a p95 read next week is not the p95 the
+ *   supervisor was implicitly competing with.
+ * - `stillMs` — the same input the supervisor got, so a replay sees what it saw.
+ * - `expect` — the plan's own note, because a ruling made with a briefing and
+ *   one made without are not the same measurement (96's critical arm).
+ * - `outcome` — what the executor observed afterwards. Mandatory.
+ *
+ * `from` separates a deterministic rule from a model answer. Both are rulings
+ * and both have outcomes, but a comparison that mixed them would credit the
+ * model for what a two-line rule decided.
+ */
+export function recordSupervision(udid, {
+  session, index, step, edge, screen, decision, from, reason, ms,
+  stillMs, p95, samples, expect, failure, outcome,
+}) {
+  // Swallowed rather than thrown, unlike `recordEscalation`'s guard, and the
+  // difference is deliberate: this is called from inside a flow's failure
+  // handler, where a throw would turn a recoverable step failure into a crash.
+  // It still lands in `lastWriteError`, which `simframe escalations` prints.
+  if (!RULING_OUTCOMES.includes(outcome)) {
+    lastWriteError = `supervision outcome must be one of ${RULING_OUTCOMES.join('/')}, got ${JSON.stringify(outcome)}`;
+    return false;
+  }
+  return appendJsonl(metricPaths(udid).supervisions, {
+    timestamp: new Date().toISOString(),
+    session_id: session ?? SESSION_ID,
+    client: CLIENT,
+    step_index: index ?? null,
+    step: step ?? null,
+    edge: edge ?? null,
+    screen_fingerprint: screen ?? null,
+    decision,
+    from: from ?? 'model',
+    // 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.
+    reason: reason ? String(reason).slice(0, 200) : null,
+    latency_ms: Number.isFinite(ms) ? Math.round(ms) : null,
+    still_ms: Number.isFinite(stillMs) ? Math.round(stillMs) : null,
+    edge_p95_ms: Number.isFinite(p95) ? Math.round(p95) : null,
+    edge_samples: Number.isFinite(samples) ? samples : null,
+    expect: expect ? String(expect).slice(0, 200) : null,
+    failure: failure ? String(failure).slice(0, 300) : null,
+    outcome,
+  });
+}
+
+/**
+ * What the ruling log currently says, and whether it can yet answer 101.
+ *
+ * Deliberately counts rather than scores. Item 101 asks which `wait`/`retry`
+ * rulings a p95-per-edge lookup would have got right, and that is a separate
+ * piece of work; what this answers is the question that comes first and was
+ * embarrassing to get wrong once already — **is there a population to measure
+ * at all, and do its rows carry the fields the measurement needs.** `p95_known`
+ * is that readiness check: a ruling recorded on an edge the graph had never
+ * timed cannot take part in the comparison, however many of them there are.
+ */
+export function supervisionBreakdown(records) {
+  const by = (key) => {
+    const out = {};
+    for (const r of records) {
+      const k = r[key] ?? 'unknown';
+      out[k] = (out[k] ?? 0) + 1;
+    }
+    return out;
+  };
+  const matrix = {};
+  for (const r of records) {
+    const k = `${r.decision ?? 'unknown'} -> ${r.outcome ?? 'unknown'}`;
+    matrix[k] = (matrix[k] ?? 0) + 1;
+  }
+  const timed = records.filter((r) => Number.isFinite(r.edge_p95_ms));
+  const latencies = records.map((r) => r.latency_ms).filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
+  return {
+    total: records.length,
+    by_decision: by('decision'),
+    by_outcome: by('outcome'),
+    by_from: by('from'),
+    decision_to_outcome: matrix,
+    // Readiness for 101, not a result for it.
+    p95_known: timed.length,
+    p95_unknown: records.length - timed.length,
+    sessions: [...new Set(records.map((r) => r.session_id).filter(Boolean))],
+    median_latency_ms: latencies.length ? latencies[latencies.length >> 1] : null,
+  };
+}
 
 /**
  * Mark an error as an escalation with a reason, at the site that knows why.

package/src/platform/android.js

@@ -996,6 +996,28 @@ function capabilities() {
   };
 }
 
+/**
+ * Not implemented here, and it says so in its own vocabulary.
+ *
+ * `revive` exists for a display that has stopped rendering — a CoreSimulator
+ * pathology. An emulator's failure modes are its own (the console port going
+ * away, adb losing the device) and the remedy is not the same sequence, so
+ * borrowing the other platform's answer would be the mistake `doctor` made when
+ * it reported "input driver: idb" for an emulator: a claim about a tool that has
+ * never spoken to an Android device.
+ *
+ * When an emulator wedge is characterised rather than guessed at, this becomes
+ * a real implementation. Until then the honest answer is that this backend does
+ * not have the layer.
+ */
+async function restartDevice(serial) {
+  throw new Error(
+    `simframe cannot yet restart an emulator (${serial}) — that remedy is written for a`
+    + ' simulator display that stopped rendering, and an emulator fails differently.'
+    + ' Restart it from Android Studio, or `adb -s <serial> emu kill` and relaunch.',
+  );
+}
+
 /** @type {import('./index.js').Platform} */
 export const platform = {
   id: 'android',
@@ -1011,6 +1033,7 @@ export const platform = {
   launchApp,
   terminateApp,
   openUrl,
+  restartDevice,
   setPermission,
   setPasteboard,
   getPasteboard,

package/src/platform/index.js

@@ -61,7 +61,7 @@ export const PLATFORM_SURFACE = Object.freeze([
   'id', 'deviceNoun',
   'listDevices', 'bootedDevices', 'resolveDevice', 'isBootedSync', 'ownsUdid',
   'geometry', 'inputDriver',
-  'screenshot', 'launchApp', 'terminateApp', 'openUrl',
+  'screenshot', 'launchApp', 'terminateApp', 'openUrl', 'restartDevice',
   'setPermission', 'setPasteboard', 'permissionServices', 'capabilities', 'toolchain',
   'bootedAt',
 ]);
@@ -260,6 +260,16 @@ export const inputDriverFor = (udid) => platformFor(udid).inputDriver(udid);
  */
 export const capabilitiesFor = (udid) => platformFor(udid).capabilities();
 
+/**
+ * Power-cycle a device, on the backend that owns it.
+ *
+ * Reached only from `simframe revive`, never from the capture loop: the loop
+ * detects a stalled display and reports it, and restarting is the operator's
+ * call. A backend that does not have this remedy throws in its own terms rather
+ * than borrowing the other's.
+ */
+export const restartDevice = (udid) => platformFor(udid).restartDevice(udid);
+
 /** What `simframe doctor` should check: each registered backend's own toolchain. */
 export function toolchainChecks() {
   return backends().flatMap((backend) => backend.toolchain());

package/src/platform/ios.js

@@ -66,6 +66,19 @@ async function bootedDevices(opts) {
  */
 async function resolveDevice(query, opts) {
   const all = await listDevices(opts);
+  return pickDevice(query, all);
+}
+
+/**
+ * Which device a query means, given the whole list.
+ *
+ * Separated from the listing so the decision can be **tested** rather than
+ * reasoned about, because two peer rounds in a row reported being handed the
+ * wrong device and both were decided here. The same move as `decisionOf` in the
+ * supervisor: the one line where a wrong answer is expensive should be a
+ * function somebody can call with adversarial input.
+ */
+export function pickDevice(query, all) {
   const booted = all.filter((d) => d.state === 'Booted');
   if (!query) {
     if (booted.length === 0) throw new Error('no booted simulator (open Simulator.app or run `xcrun simctl boot <udid>`)');
@@ -98,8 +111,40 @@ async function resolveDevice(query, opts) {
   const q = query.toLowerCase();
   const pools = [booted, all];
   for (const pool of pools) {
-    const exact = pool.find((d) => d.udid.toLowerCase() === q || d.name.toLowerCase() === q);
-    if (exact) return exact;
+    // A UDID is unique, so an exact UDID match needs no further thought.
+    const byUdid = pool.find((d) => d.udid.toLowerCase() === q);
+    if (byUdid) return byUdid;
+    // A **name is not unique**, and this branch used to treat it as though it
+    // were: one `find` over both fields returned whichever device the list
+    // happened to put first, and short-circuited past the ambiguity guard
+    // below. Item 83 recorded that two booted devices on this machine are both
+    // called "iPhone 17 Pro" and answered it by warning in `sim_devices` and
+    // printing a UDID prefix in headers — leaving the resolver, which is where
+    // the choice is actually made, untouched.
+    //
+    // What that cost, reported from a three-hour session on a real app: a
+    // caller passed the shared name, read a screen that was "38ms old" and an
+    // hour wrong, concluded the app had signed itself out, and abandoned a
+    // verification run that was fine. The frame was fresh — it was the *other*
+    // device's, idling on a login screen. `refresh: true` returned the matching
+    // tree because it refreshed the same wrong device. Two independent-looking
+    // sources agreeing with each other and both wrong.
+    //
+    // So a name that names two devices is an ambiguity, exactly like a partial
+    // match that hits two, and it refuses for the same reason: the cost of
+    // guessing wrong is reading somebody else's screen and believing it.
+    const byName = pool.filter((d) => d.name.toLowerCase() === q);
+    if (byName.length === 1) return byName[0];
+    if (byName.length > 1) {
+      throw Object.assign(
+        new Error(
+          `"${query}" is the name of ${byName.length} devices: `
+          + `${byName.map((d) => d.udid).join(', ')} — a name cannot say which one you mean, `
+          + 'so pass the UDID',
+        ),
+        { ambiguous: true },
+      );
+    }
     const partial = pool.filter((d) => d.name.toLowerCase().includes(q));
     if (partial.length === 1) return partial[0];
     if (partial.length > 1) {
@@ -189,6 +234,28 @@ async function openUrl(udid, url) {
   await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: 20_000 });
 }
 
+/**
+ * Shut a device down and bring it back, waiting for the boot to finish.
+ *
+ * The remedy for a display that has stopped rendering, which the capture loop
+ * can detect and must not perform: it reports `stalled` and stops, because a
+ * capture loop that rebooted the device it was watching would be a tool
+ * reaching for the mains when a reading looks wrong. This is the operator's
+ * decision, reached by `simframe revive`.
+ *
+ * `bootstatus -b` and not `boot`, for the reason it is used in CI: `boot`
+ * returns before the device is usable, and everything downstream then races the
+ * boot. Timeboxed generously — a cold boot on a busy machine is slow, and a
+ * boot that never finishes should fail here with a reason rather than as a
+ * puzzle further down.
+ */
+async function restartDevice(udid) {
+  // Tolerated: a device that is already off cannot be shut down, and that is
+  // the state this command is most often reached from.
+  await run('xcrun', ['simctl', 'shutdown', udid], { timeout: 60_000 }).catch(() => null);
+  await run('xcrun', ['simctl', 'bootstatus', udid, '-b'], { timeout: 240_000 });
+}
+
 const PERMISSION_SERVICES = [
   'all', 'calendar', 'contacts-limited', 'contacts', 'location', 'location-always',
   'photos-add', 'photos', 'media-library', 'microphone', 'motion', 'reminders', 'siri',
@@ -347,6 +414,7 @@ export const platform = {
   launchApp,
   terminateApp,
   openUrl,
+  restartDevice,
   setPermission,
   setPasteboard,
   permissionServices: () => PERMISSION_SERVICES,

package/src/regions.js

@@ -24,6 +24,27 @@ export const REGIONS = [
   'content',
 ];
 
+/**
+ * Regions the screen map will not offer as something to act on.
+ *
+ * The status bar says the time and the battery level. It is on every screen, it
+ * is never what anybody wants to tap, and it costs a row every time — so
+ * `sim_ui` hides it.
+ *
+ * It lives here rather than in `view.js`, where it started, because it is not
+ * only a presentation rule. A target the map refuses to *show* must also be a
+ * target nothing may resolve onto *behind the caller's back*, and the case that
+ * proved it was exactly that: a stale `#1` numbered "Reminders" in Reminders,
+ * re-resolved in Contacts onto the status-bar back-to-app breadcrumb
+ * "• Reminders", scored 0.64 and handed back a tap point at (47,40) — a place
+ * the map would never have put in front of anybody. One rule, one home, both
+ * readers.
+ */
+const UNOFFERED_REGIONS = new Set(['status-bar']);
+
+/** Would the screen map offer a target in this region? */
+export const offerable = (region) => !UNOFFERED_REGIONS.has(region);
+
 /**
  * The status bar stays positional, and deliberately.
  *
@@ -63,6 +84,46 @@ const BOTTOM_CHROME_LIMIT = 0.82;
  * screen sets its own scale.
  */
 const MIN_BOUNDARY_GAP_PT = 10;
+/**
+ * How wide a lone row may be and still be a screen's title rather than its
+ * first paragraph.
+ *
+ * 0.6 of the screen, measured: the Settings root's large title is 133 pt of
+ * 402 (0.33), while Reminders' empty-state heading "Welcome to Reminders" is
+ * 326 pt (0.81) and is content — it describes the screen instead of naming it.
+ * A title is a name and names are short.
+ */
+const LARGE_TITLE_MAX_WIDTH_FRACTION = 0.6;
+/**
+ * How far below the status bar a large title can start.
+ *
+ * iOS draws one at a **system** offset, not an app-chosen one, so this is a
+ * bound on a platform constant rather than a tuned threshold. Measured on the
+ * bench device: the Settings root's title starts 63-79 pt below the status bar
+ * depending on which sensor reports its box, while example.com's `<h1>` — page
+ * *content* that merely happens to be the first row, because Safari on iOS puts
+ * its chrome at the bottom — starts **122 pt** down.
+ *
+ * Without this bound the rule promoted that `<h1>` to chrome and "example
+ * domain" entered the screen's identity. Pulling page content into identity is
+ * the exact failure this module has been bitten by twice (a phantom keyboard,
+ * and content that merely fell into a band), so the bound is not optional.
+ */
+const LARGE_TITLE_MAX_INSET_PT = 96;
+/**
+ * And the least it can be, before it is just the next row.
+ *
+ * Absolute, like the maximum, and for the same reason: the inset is drawn by
+ * the system, so it is not a function of what the screen contains. The first
+ * version tested it against the screen's *median row gap* — and the testbed
+ * caught that on its first day, with two screens of the same app. A list of 24
+ * rows has a median gap of 0 and the rule fired; a list of 4 rows above a tab
+ * bar has a median gap of **414**, because the empty area counts as a gap, and
+ * the rule did not. Same title, same inset of 62.9pt, opposite answers — so one
+ * screen had a name in its identity and the other did not, and the graph then
+ * called them the same screen at 0.50 similarity.
+ */
+const LARGE_TITLE_MIN_INSET_PT = 24;
 const BOUNDARY_GAP_FACTOR = 1.9;
 
 /** A tab bar is several things spread across the width, not one thing at the bottom. */
@@ -177,6 +238,50 @@ export function bands(elements, screen) {
     }
   }
 
+  // --- a large title, which has no gap under it to be found by.
+  //
+  // The loop above identifies top chrome by the whitespace *beneath* it, and an
+  // iOS large title is drawn tight against the content it heads: measured on
+  // the Settings root, 79 pt of inset above it and **5.3 pt** below, against a
+  // bar of `max(10, typical * 1.9)` = 66.5. No threshold reaches that, so the
+  // title fell into `content` and was discarded as content — leaving the screen
+  // with **no name at all** in its fingerprint, in either sensor mode.
+  //
+  // That is not cosmetic. Chrome labels are the only text identity keeps, and
+  // `fingerprint.js` names the consequence: two list screens with identical
+  // structure differ by their title and nothing else says so. A nameless screen
+  // is pure geometry, and on a hosted runner two sparse nameless readings
+  // matched exactly — one screen's hash for two screens.
+  //
+  // So it is found by the inset *above* it instead, which is the half iOS does
+  // provide. A large title sits alone, narrow, high, under a generous gap; a
+  // compact bar is the mirror image of that (20-33 pt above, 118-134 below) and
+  // is already caught by the loop. Deliberately not keyed on the `Heading`
+  // role: OCR has no roles, and the reading that actually collided was
+  // OCR-only, so a role test would work only in the case that does not fail.
+  //
+  // Measured across all 17 perception fixtures before being written here: it
+  // changes exactly one of them, the Settings root.
+  if (!navBarBottom) {
+    const first = rows.findIndex((r) => r.top >= statusBarBottom - 1);
+    const row = first >= 0 ? rows[first] : null;
+    if (
+      row
+      && first + 1 < rows.length
+      && row.items.length === 1
+      && (row.items[0].frame?.width ?? 0) <= screen.width * LARGE_TITLE_MAX_WIDTH_FRACTION
+      && row.bottom <= screen.height * TOP_CHROME_LIMIT
+      // A real separation from the status bar, but a system-sized one: far
+      // enough to be an inset, near enough to still be the app's own title.
+      // Both bounds absolute — see LARGE_TITLE_MIN_INSET_PT for what keying the
+      // lower one on the screen's own row rhythm cost.
+      && row.top - statusBarBottom >= LARGE_TITLE_MIN_INSET_PT
+      && row.top - statusBarBottom <= LARGE_TITLE_MAX_INSET_PT
+    ) {
+      navBarBottom = row.bottom;
+    }
+  }
+
   // --- bottom chrome. One row: a tab bar is one row by construction, and the
   // gap above it is what separates it from the list it floats over.
   let tabBarTop = Infinity;

package/src/supervisor.js

@@ -45,6 +45,30 @@ const helper = lineServer({
 
 export const DECISIONS = new Set(['wait', 'retry', 'stop']);
 
+/**
+ * The vocabulary gate, as a function so it can be *tested* rather than grepped.
+ *
+ * This one line is the safety property: the supervisor cannot invent a step,
+ * skip one, substitute a target or continue past an unexpected screen, because
+ * those are not words it can say. Anything outside the three is not a decision
+ * and becomes `null`, which means "behave as if there is no supervisor".
+ *
+ * It was previously inline, and the test that guarded it matched the source
+ * text — so it broke when the branch grew an else, with nothing actually wrong.
+ * A property this important deserves an assertion that runs it.
+ */
+export function decisionOf(answer) {
+  // A string, checked rather than coerced. `String(["wait"])` is `"wait"`, so a
+  // `String(...)` coercion here let `{decision: ["wait"]}` through the one gate
+  // that defines this component's answer space. Found the first time this
+  // property was *run* instead of grepped for in the source — the old test
+  // matched the source text of the branch and could never have caught it.
+  const raw = answer?.decision;
+  if (typeof raw !== 'string') return null;
+  const decision = raw.toLowerCase();
+  return DECISIONS.has(decision) ? decision : null;
+}
+
 /** Which backend the caller asked for, per call first and environment second. */
 export function requested(options) {
   const raw = String(options?.supervisor ?? process.env.SIMFRAME_SUPERVISOR ?? '').trim().toLowerCase();
@@ -62,6 +86,7 @@ export function requested(options) {
  */
 export async function judge({
   goal, step, expected, failure, screen, stillMs, note, options, timeoutMs = 2500,
+  detail,
 } = {}) {
   if (!requested(options)) return null;
   if (!step || !failure) return null;
@@ -74,10 +99,24 @@ export async function judge({
     stillMs: Number.isFinite(stillMs) ? Math.round(stillMs) : null,
     note: note ? String(note).slice(0, 200) : null,
   }, timeoutMs);
-  const decision = String(answer?.decision ?? '').toLowerCase();
-  // An answer outside the vocabulary is not a decision. Refusing it here is
-  // what makes the three-word constraint real rather than merely documented.
-  if (!DECISIONS.has(decision)) return null;
+  const decision = decisionOf(answer);
+  if (decision == null) {
+    // Why it did not answer, for the caller's log — through an out-parameter
+    // rather than the return value, because returning anything truthy here
+    // would change what the executor does. `null` means "behave as if there is
+    // no supervisor" and that safety property is the one thing in this file
+    // that must not become conditional.
+    //
+    // Before this, every failure reached the supervision log as "the
+    // supervisor did not answer": a timeout, a guardrail refusal and a model
+    // that was never installed were one indistinguishable line.
+    if (detail && typeof detail === 'object') {
+      detail.kind = answer?.kind
+        ?? (answer == null ? 'no answer' : answer.decision ? 'outside the vocabulary' : 'unparseable');
+      if (answer?.error) detail.error = String(answer.error).slice(0, 200);
+    }
+    return null;
+  }
   return { decision, reason: String(answer.reason ?? '').slice(0, 120), ms: answer.ms ?? null };
 }
 
@@ -101,16 +140,21 @@ export async function status(options) {
     screen: ['Probe'],
     stillMs: 5000,
   }, 6000);
-  const decision = String(probe?.decision ?? '').toLowerCase();
-  if (!DECISIONS.has(decision)) {
+  if (decisionOf(probe) == null) {
     return {
       supervisor: 'none',
       detail: 'the model loaded but did not answer a probe — it is present and not working',
     };
   }
+  // The window, read from the model rather than repeated from documentation.
+  // Worth printing: the worst case our own clipping allows measures 1,918
+  // tokens against it, and that ratio is the reason there is no per-call token
+  // budget check — see DEFERRED 99.
+  const ctx = live.hello?.contextSize;
   return {
     supervisor: 'apple',
-    detail: `Apple Foundation Models, on-device; answered a probe in ${probe.ms ?? '?'}ms; may only answer wait/retry/stop`,
+    detail: `Apple Foundation Models, on-device; answered a probe in ${probe.ms ?? '?'}ms;`
+      + `${ctx ? ` ${ctx}-token window;` : ''} may only answer wait/retry/stop`,
   };
 }