simframe 0.12.2 → 0.14.0

package/src/platform/plist.js

@@ -0,0 +1,156 @@
+// Property lists, parsed without a dependency.
+//
+// Below the platform boundary on purpose. A plist is not a neutral file format
+// this project happens to read — it is how one platform stores what an app
+// believes, and `plutil` is that platform's tool. Android's answer to the same
+// question is a different file in a different shape, which is why the parsing
+// lives beside the backend that needs it rather than above the seam.
+//
+// **Why XML and not JSON.** `plutil -convert json` is the obvious route and it
+// does not work: measured across the twenty real `Library/Preferences` plists
+// on the bench device, **six of them failed to convert** — 30%, because JSON
+// has no representation for `<data>` or `<date>` and plutil refuses rather than
+// inventing one. `-convert xml1` succeeded on all twenty. A format that drops
+// three in ten real files is not a parser, it is a sampler.
+//
+// The XML here is machine-written by plutil, so this is a reader for that
+// output and not a general XML parser: no namespaces, no processing
+// instructions beyond the declaration, no mixed content. It is strict about
+// what it does not understand — an unknown tag throws rather than being skipped,
+// because a silently dropped key in a store read is a wrong answer about what
+// an app believes, and this whole feature exists to be trusted on that point.
+
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** Decode the five XML entities plutil emits, plus numeric escapes. */
+export function decodeEntities(s) {
+  return String(s).replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (whole, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return ENTITIES[body] ?? whole;
+  });
+}
+
+/**
+ * A `<data>` value.
+ *
+ * Kept as a tagged object rather than decoded to a Buffer or dropped. The
+ * caller is usually a human asking what an app persisted, and "a 4 KB blob"
+ * is a real and often sufficient answer — while silently omitting the key
+ * would misreport the store as not having it.
+ */
+const dataValue = (base64) => {
+  const clean = base64.replace(/\s+/g, '');
+  return {
+    __type: 'data',
+    bytes: Math.floor((clean.length * 3) / 4) - (clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0),
+    base64: clean,
+  };
+};
+
+/**
+ * Parse the XML property list plutil writes.
+ *
+ * @param {string} xml output of `plutil -convert xml1 -o -`
+ * @returns {*} the plist's root value — normally an object
+ */
+export function parse(xml) {
+  const src = String(xml);
+  // Everything before <plist> is the declaration and the DOCTYPE, neither of
+  // which carries data.
+  const start = src.indexOf('<plist');
+  if (start < 0) throw new Error('not an XML property list (no <plist> element)');
+  let i = src.indexOf('>', start);
+  if (i < 0) throw new Error('not an XML property list (unterminated <plist>)');
+  i += 1;
+
+  /** The next tag at or after `i`, skipping text that is only whitespace. */
+  const nextTag = () => {
+    const open = src.indexOf('<', i);
+    if (open < 0) return null;
+    const close = src.indexOf('>', open);
+    if (close < 0) throw new Error('unterminated tag in property list');
+    const raw = src.slice(open + 1, close);
+    i = close + 1;
+    const selfClosing = raw.endsWith('/');
+    const name = raw.replace(/\/$/, '').trim().split(/\s/)[0];
+    return { name: name.replace(/^\//, ''), closing: raw.startsWith('/'), selfClosing };
+  };
+
+  /** Text up to the matching close tag, which plutil never nests inside a leaf. */
+  const textUntilClose = (tag) => {
+    const close = src.indexOf(`</${tag}>`, i);
+    if (close < 0) throw new Error(`unterminated <${tag}> in property list`);
+    const text = src.slice(i, close);
+    i = close + tag.length + 3;
+    return text;
+  };
+
+  const readValue = (tag) => {
+    switch (tag.name) {
+      case 'true': return true;
+      case 'false': return false;
+      case 'string': return tag.selfClosing ? '' : decodeEntities(textUntilClose('string'));
+      case 'integer': {
+        const text = textUntilClose('integer').trim();
+        const n = Number(text);
+        // A plist integer is 64-bit and JavaScript's is not. Returning a
+        // silently-rounded number would be a wrong answer about a stored value,
+        // so the exact digits survive as a string and the shape says why.
+        if (!Number.isSafeInteger(n)) return { __type: 'integer', exact: text };
+        return n;
+      }
+      case 'real': return Number(textUntilClose('real').trim());
+      case 'date': return { __type: 'date', iso: textUntilClose('date').trim() };
+      case 'data': return dataValue(textUntilClose('data'));
+      case 'dict': {
+        if (tag.selfClosing) return {};
+        const out = {};
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <dict> in property list');
+          if (t.closing && t.name === 'dict') return out;
+          if (t.name !== 'key') throw new Error(`expected <key> in <dict>, found <${t.name}>`);
+          const key = t.selfClosing ? '' : decodeEntities(textUntilClose('key'));
+          const vt = nextTag();
+          if (!vt) throw new Error(`<key>${key}</key> has no value`);
+          out[key] = readValue(vt);
+        }
+      }
+      case 'array': {
+        if (tag.selfClosing) return [];
+        const out = [];
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <array> in property list');
+          if (t.closing && t.name === 'array') return out;
+          out.push(readValue(t));
+        }
+      }
+      default:
+        // Deliberately not a skip. See the note at the top of this file.
+        throw new Error(`unsupported property-list element <${tag.name}>`);
+    }
+  };
+
+  const root = nextTag();
+  if (!root || root.closing) return null;
+  return readValue(root);
+}
+
+/**
+ * What kind of thing a parsed value is, in one word, for a listing.
+ *
+ * `typeof` is not enough: the tagged shapes above are objects, and calling a
+ * date "object" in a store listing tells the reader nothing they wanted.
+ */
+export function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return value.__type ?? 'dict';
+  return typeof value;
+}

package/src/refs.js

@@ -149,7 +149,18 @@ export function resolveRef(udid, n, { structuralHash, layoutHash, screenKnown, s
   // numbers. Refusing costs a re-read; guessing taps whatever is at those
   // coordinates now.
   if (screenKnown === false) {
-    throw new Error(`#${n} cannot be trusted here — simframe does not recognise this screen. Read it again (sim_ui) to renumber.`);
+    // Flagged, like every other refusal in this function, and it was the one
+    // that was not.
+    //
+    // We tell callers to read `staleRef` rather than the sentence — the CI check
+    // for this very guard carries a comment saying it matched on prose twice and
+    // went red twice, so it reads the contract now. Then it went red a third
+    // time, on a refusal that was correct, well worded, and carried no field at
+    // all: `#1 cannot be trusted here — simframe does not recognise this
+    // screen`, reported by the harness as `no reason`. A refusal a human can
+    // read and a program cannot is the same defect as a failure that reads like
+    // a success, one level down.
+    throw staleError('simframe does not recognise this screen', 'unknown-screen');
   }
   // The pixel check stays, but only as a backstop, and only where it means
   // something. A dark or near-uniform screen produces a layout hash of almost

package/src/regions.js

@@ -470,6 +470,60 @@ export function offViewport(t, screen) {
   return false;
 }
 
+/**
+ * The smallest sliver of an element that is worth offering as a tap target.
+ *
+ * Apple's own minimum touch target is 44pt; this is deliberately smaller,
+ * because the question here is not "is this comfortable to tap" but "is this a
+ * real control a person can see and reach". A filter chip showing 29pt of
+ * itself at the edge of a horizontal strip is both. Below this, what is on
+ * screen is bleed rather than a control.
+ */
+export const MIN_VISIBLE_PT = 24;
+
+/**
+ * How much of an element is actually on screen, and where to tap what is.
+ *
+ * `offViewport` answers a yes/no question about the element's *centre*, which
+ * is right for "should I scroll to reach this" and wrong for "is this here at
+ * all". A chip at the end of a horizontal strip showed **29pt of itself** on a
+ * 402pt screen — real, visible, tappable — while its centre sat at x=416, so it
+ * was dropped from the map entirely. What the caller got in its place was OCR's
+ * reading of the visible sliver: a `text` element labelled **"Flc"** at x=392,
+ * which passes every filter because its own box is inside the viewport.
+ *
+ * So the map did not merely omit a control. It offered a different, meaningless
+ * name for it, at a coordinate that looks perfectly ordinary. That is the shape
+ * of item 121 — a caller who cannot trust what the map says about the edge of
+ * the screen — and the item's own words are "say so or clamp". This does both.
+ */
+export function clipping(t, screen) {
+  const f = t?.frame;
+  const w = screen?.width;
+  const h = screen?.height;
+  if (!f || !Number.isFinite(w) || !Number.isFinite(h)) return null;
+  const left = Math.max(0, f.x);
+  const right = Math.min(w, f.x + f.width);
+  const top = Math.max(0, f.y);
+  const bottom = Math.min(h, f.y + f.height);
+  const visibleWidth = right - left;
+  const visibleHeight = bottom - top;
+  if (visibleWidth <= 0 || visibleHeight <= 0) {
+    return { visibleWidth: 0, visibleHeight: 0, clipped: true, usable: false, point: null };
+  }
+  const clipped = f.x < 0 || f.y < 0 || f.x + f.width > w || f.y + f.height > h;
+  return {
+    visibleWidth,
+    visibleHeight,
+    clipped,
+    usable: visibleWidth >= MIN_VISIBLE_PT && visibleHeight >= MIN_VISIBLE_PT,
+    // The centre of what can be seen, not the centre of the element. Tapping
+    // the latter would aim off the screen, which is the clamp the item asked
+    // for and the reason a caller could not simply be handed the real centre.
+    point: { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) },
+  };
+}
+
 /** Annotate a target list with region and nav slot. Mutates and returns it. */
 export function annotate(targets, screen) {
   const band = bands(targets, screen);

package/src/screenmap.js

@@ -296,15 +296,64 @@ export async function build(udid, {
     try {
       // The tree is already in hand when the daemon answered; describeAll would
       // only ask for it a second time.
-      const nodes = daemonScreen?.sources?.includes('ax')
-        ? daemonScreen.elements.filter((e) => e.source?.includes('ax')).map(input.elementToNode)
-        : await input.describeAll(udid);
+      //
+      // And when the daemon answered *without* a tree, asking again is asking
+      // the thing that just failed. That path cost a red CI run and a wrong
+      // diagnosis: the daemon's ax read timed out, `describeAll` re-asked it
+      // (another 20s), got the same nothing, fell through to idb, and the map
+      // reported **"idb is not installed, so simframe can observe the screen but
+      // cannot touch it"**. A sentence about a tool this project deliberately
+      // does not use on CI, printed because a different tool had a bad read —
+      // and it points whoever reads it at installing idb, which would change
+      // nothing. The same read worked a minute later.
+      //
+      // The daemon has sent `axError` since it learned to time its own reads,
+      // and nothing here had ever read it. The OCR branch below reads
+      // `ocrError`, which is what makes the asymmetry visible: one sensor could
+      // say why it failed and the other borrowed a different tool's excuse.
+      let nodes;
+      if (daemonScreen?.sources?.includes('ax')) {
+        nodes = daemonScreen.elements.filter((e) => e.source?.includes('ax')).map(input.elementToNode);
+      } else if (daemonScreen) {
+        throw new Error(daemonScreen.axError ?? 'the daemon read the screen and the accessibility tree did not answer');
+      } else {
+        nodes = await input.describeAll(udid);
+      }
 
       sources.push('ax');
+      // A control the tree gives no name to is still a control — item 122.
+      //
+      // This line used to read `!n.label`, on the reasoning that a row nobody
+      // can name is a row nobody can tap. The whole of item 122 is that the
+      // opposite is true, and three field reports in a row said so
+      // independently: icon-only overflow menus on every card, a bottom-sheet
+      // drag handle, a back chevron. Real, tappable, on screen, and absent from
+      // the map — so every one of them needed a raw `@x,y` read off a
+      // screenshot, which is the exact round trip the text map exists to
+      // remove. Knowing that *a hit target is there* is most of the value even
+      // with no semantics attached to it.
+      //
+      // Measured on the testbed before it was written, because the premise
+      // could have been false: on the list screen, of 39 accessibility nodes
+      // exactly **one** is nameless — and it is the one control on that screen
+      // no caller could reach. This does not flood the map.
+      //
+      // It also settles a thing the reports could not: those controls were
+      // called "absent from the tree", and AXPTranslator had them all along.
+      // What is genuinely absent is the drag handle, a plain view holding a
+      // responder that UIKit is never told is accessible. No filter here can
+      // recover that one; see 122's second half.
       for (const n of nodes) {
-        if (!n.frame || !n.label || isContainer(n)) continue;
+        if (!n.frame || isContainer(n)) continue;
+        if (nameless(n) && !namelessHitTarget(n, nodes)) continue;
         targets.push({
-          label: n.label,
+          label: n.label ?? undefined,
+          // A `testID` arrives as AXIdentifier, and `tap` has matched on it
+          // since long before this — but only down the tree path, because the
+          // map never carried it. So the one name an unlabelled React Native
+          // control usually does have was invisible in the map and worked if
+          // you guessed it.
+          identifier: n.identifier ?? undefined,
           // What the control *contains*, whether it is on, and whether it has
           // focus. All three come off the accessibility tree, the daemon has
           // asked for all three since 0.6.0, and all three were dropped before
@@ -506,6 +555,36 @@ export function isInteractive(target) {
   return INTERACTIVE.test(target.type || '');
 }
 
+/** No name from any source: not a label, not an identifier. */
+export const nameless = (n) => !n?.label && !n?.identifier;
+
+/**
+ * Whether a nameless accessibility node is worth printing as a hit target.
+ *
+ * Two guards, because "has no name" is not the same as "is a control".
+ *
+ * The role has to be one the tree calls interactive. A nameless `Other` is a
+ * layout view and a real screen has hundreds of them; emitting those would bury
+ * the one node that matters under the scenery it sits in.
+ *
+ * And it must not enclose two or more other elements. That is the same test the
+ * fingerprint uses for scenery, reused deliberately rather than invented here:
+ * a table cell holding its own labels is not the target, its labels are.
+ */
+export function namelessHitTarget(node, nodes) {
+  const f = node?.frame;
+  if (!f || !(f.width > 0) || !(f.height > 0)) return false;
+  if (!INTERACTIVE.test(node.type || '')) return false;
+  const encloses = nodes.filter((o) => {
+    const g = o.frame;
+    if (!g || o === node) return false;
+    const cx = g.x + (g.width ?? 0) / 2;
+    const cy = g.y + (g.height ?? 0) / 2;
+    return cx > f.x && cx < f.x + f.width && cy > f.y && cy < f.y + f.height;
+  }).length;
+  return encloses < 2;
+}
+
 /**
  * Rank candidates for a label. Exact beats substring, and a real control beats
  * a caption that happens to read the same — a screen title and a tab are often
@@ -514,7 +593,7 @@ export function isInteractive(target) {
 export function rank(entry, query) {
   if (!entry) return [];
   const q = norm(query);
-  const names = (t) => [t.label, ...(t.aliases || [])].map(norm);
+  const names = (t) => [t.label, t.identifier, ...(t.aliases || [])].map(norm);
   const exact = entry.targets.filter((t) => names(t).includes(q));
   const pool = exact.length
     ? exact

package/src/storage.js

@@ -0,0 +1,201 @@
+// What the app believes.
+//
+// The perception tools answer "what is drawn". This answers "what did the app
+// save", and the field report that asked for it put the pairing better than we
+// did: *"`sim_ui` says what is drawn, `sim_storage` says what the app
+// believes."* Their highest-leverage moment in a whole session was not a
+// simframe call at all — they read the persisted store straight out of the data
+// container, found the exact wrong value the app had written, and proved the bug
+// with no live session, no login, and the device not yet booted.
+//
+// That last property is the design constraint, not a bonus. Measured on this
+// Xcode, `simctl get_app_container` and `simctl listapps` both refuse on a
+// device that is not running. So nothing here goes through the device: the
+// backend reads the container off the host filesystem, and a shut-down device
+// answers exactly as well as a running one.
+//
+// Nothing in this file knows which platform it is on. Where a container lives
+// and how a property list is decoded are the backend's business; what a store
+// is, and how to say what is in one, are this file's.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import * as platform from './platform/index.js';
+
+/**
+ * How much of a single value is printed before the rest is summarised.
+ *
+ * Generous on purpose — the whole point is to see what the app actually wrote,
+ * and a value clipped to eighty characters answers nothing. What this must
+ * never do is clip *silently*: item 141 in DEFERRED is a harness that cut a
+ * failure report one character before the only content that mattered, and the
+ * lesson was that a reader who is not told about a cut reads the fragment as
+ * the whole. So past this, the text says how many bytes it is not showing and
+ * how to get them.
+ */
+export const VALUE_PREVIEW_BYTES = 4096;
+
+/** React Native's own store, in the layout its iOS implementation writes. */
+const ASYNC_STORAGE_DIR = 'RCTAsyncLocalStorage_V1';
+const ASYNC_STORAGE_MANIFEST = 'manifest.json';
+
+/** Files that are plainly a store but that nothing here can decode yet. */
+const OPAQUE_STORES = /\.(sqlite3?|db|realm|leveldb|mmkv)$/i;
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+const sizeOf = (file) => { try { return fs.statSync(file).size; } catch { return null; } };
+
+/** Every app with a data container on the device, whether or not it is running. */
+export async function apps(udid) {
+  return platform.listApps(udid);
+}
+
+/**
+ * React Native's AsyncStorage.
+ *
+ * The manifest holds small values inline. A value past RN's inline threshold is
+ * stored as `null` in the manifest and written to a file beside it named by the
+ * MD5 of the key — so a manifest full of nulls is not an empty store, and
+ * reporting it as one would be the exact class of wrong answer this feature
+ * exists to stop.
+ */
+export function readAsyncStorage(container) {
+  const dir = path.join(container, 'Documents', ASYNC_STORAGE_DIR);
+  const manifestPath = path.join(dir, ASYNC_STORAGE_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+  const manifest = readJson(manifestPath);
+  const entries = [];
+  for (const [key, inline] of Object.entries(manifest)) {
+    if (inline !== null && inline !== undefined) {
+      entries.push({ key, value: inline, type: typeof inline, where: 'manifest' });
+      continue;
+    }
+    const spilled = path.join(dir, crypto.createHash('md5').update(key).digest('hex'));
+    if (fs.existsSync(spilled)) {
+      const value = fs.readFileSync(spilled, 'utf8');
+      entries.push({ key, value, type: 'string', bytes: sizeOf(spilled), where: 'spilled to its own file' });
+    } else {
+      // Say which of the two this is. "Null" and "too big to inline, and the
+      // file is missing" are different facts about the app.
+      entries.push({ key, value: null, type: 'null', where: 'manifest says null and no spill file exists' });
+    }
+  }
+  return { name: 'AsyncStorage', source: dir, entries };
+}
+
+/**
+ * Preference plists in the container.
+ *
+ * The one named after the bundle id is the app's own `UserDefaults`; the others
+ * are real and are named rather than hidden, because a framework writing its
+ * state beside the app's is often exactly what the reader is hunting.
+ */
+async function readPreferences(udid, container, bundleId) {
+  const dir = path.join(container, 'Library', 'Preferences');
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.plist'));
+  } catch {
+    return [];
+  }
+  const stores = [];
+  for (const file of files.sort()) {
+    const full = path.join(dir, file);
+    const own = file === `${bundleId}.plist`;
+    try {
+      const parsed = await platform.readPropertyList(udid, full);
+      stores.push({
+        name: own ? 'UserDefaults' : `UserDefaults (${file.replace(/\.plist$/, '')})`,
+        source: full,
+        entries: Object.entries(parsed ?? {}).map(([key, value]) => ({ key, value, type: typeOf(value) })),
+      });
+    } catch (err) {
+      // Degrade rather than fail: one unreadable plist must not cost the
+      // reader every other store in the container.
+      stores.push({ name: own ? 'UserDefaults' : file, source: full, entries: [], error: err.message });
+    }
+  }
+  // The app's own defaults first; that is what was asked about.
+  return stores.sort((a, b) => Number(b.name === 'UserDefaults') - Number(a.name === 'UserDefaults'));
+}
+
+/** Stores that are plainly present and that nothing here can decode. */
+export function opaqueStores(container) {
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (OPAQUE_STORES.test(e.name)) found.push({ file: path.relative(container, full), bytes: sizeOf(full) });
+    }
+  };
+  walk(container, 0);
+  return found;
+}
+
+/** One word for what a value is, including the tagged shapes a plist produces. */
+export function typeOf(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return value.__type ?? 'dict';
+  return typeof value;
+}
+
+/**
+ * Everything one app has persisted that this can read, and an honest list of
+ * what it could not.
+ */
+export async function read(udid, bundleId) {
+  const container = await platform.appContainer(udid, bundleId);
+  const stores = await readPreferences(udid, container, bundleId);
+  const async_ = readAsyncStorage(container);
+  if (async_) stores.push(async_);
+  return { bundleId, container, stores, opaque: opaqueStores(container) };
+}
+
+/** One value, rendered for reading, saying so whenever it is not the whole thing. */
+export function renderValue(value) {
+  if (value && typeof value === 'object' && value.__type === 'data') {
+    return `<${value.bytes} bytes of data> ${value.base64.slice(0, 64)}${value.base64.length > 64 ? '…' : ''}`;
+  }
+  if (value && typeof value === 'object' && value.__type === 'date') return value.iso;
+  if (value && typeof value === 'object' && value.__type === 'integer') return value.exact;
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  if (text == null) return String(value);
+  if (text.length <= VALUE_PREVIEW_BYTES) return text;
+  // Announced, never silent. See VALUE_PREVIEW_BYTES.
+  return `${text.slice(0, VALUE_PREVIEW_BYTES)}\n    … ${text.length - VALUE_PREVIEW_BYTES} more character(s) not shown`
+    + ' — read the file named under `from:` for the whole value';
+}
+
+/** The text form: what the app believes, one store at a time. */
+export function format(result) {
+  const lines = [`${result.bundleId}`, `  container ${result.container}`];
+  if (!result.stores.length) lines.push('  no readable store — the app has persisted nothing this can decode');
+  for (const store of result.stores) {
+    lines.push('');
+    lines.push(`  ${store.name} — ${store.entries.length} key(s)`);
+    lines.push(`  from: ${store.source}`);
+    if (store.error) lines.push(`    unreadable: ${store.error}`);
+    for (const e of store.entries) {
+      const where = e.where && e.where !== 'manifest' ? `  (${e.where})` : '';
+      lines.push(`    ${e.key}  [${e.type}]${where}`);
+      lines.push(`      ${renderValue(e.value).split('\n').join('\n      ')}`);
+    }
+  }
+  if (result.opaque?.length) {
+    lines.push('');
+    lines.push(`  ${result.opaque.length} store(s) present that this cannot decode yet:`);
+    for (const o of result.opaque) lines.push(`    ${o.file}  ${o.bytes} bytes`);
+  }
+  return lines.join('\n');
+}
+
+/** The listing form. */
+export function formatApps(list) {
+  if (!list.length) return 'no app has a data container on this device';
+  return [`${list.length} app(s) with a data container`, ...list.map((a) => `  ${a.bundleId}`)].join('\n');
+}

package/src/store.js

@@ -34,10 +34,63 @@ export function paths(udid) {
     // wedged. It cannot ride in state.json: that is written when a frame is
     // recorded, and a stall is the absence of frames.
     captureHealth: path.join(dir, 'capture-health.json'),
+    lastInput: path.join(dir, 'last-input'),
   };
 }
 
 /** What the capture loop last said about its own health, or null if it has no complaint. */
+/**
+ * When input was last delivered to this device.
+ *
+ * Written by every input path and read by `liveness`, which needs it to catch
+ * the one wedge shape nothing else can see: a capture loop that is alive,
+ * incrementing its frame counter, and re-reading a **dead surface**. Field
+ * report, 0.12.2: `age=268ms` next to `stable=159753ms` while three screen
+ * transitions had just happened, and no warning fired because every signal we
+ * had was green. A screen that has not moved since before we last touched it,
+ * over and over, is a contradiction the daemon can notice locally.
+ */
+const INPUT_MEMORY = 8;
+
+export function noteInput(udid, at = Date.now()) {
+  try {
+    writeAtomic(paths(udid).lastInput, [...inputTimes(udid), at].slice(-INPUT_MEMORY).join(','));
+  } catch {
+    /* a timestamp nothing depends on for correctness must not fail an action */
+  }
+}
+
+/**
+ * The last few input timestamps, oldest first.
+ *
+ * A list rather than a single timestamp, and that is the whole correction.
+ * The first version kept only the latest, so the only question it could ask was
+ * "has the screen been still for a long time?" — which needed a duration
+ * threshold, and the threshold is what defeated it. A field report caught a
+ * three-hour-stale frame on a screen that had been still for **8.2 seconds**,
+ * under a 20-second gate, so the check could not fire on the case it was
+ * written for.
+ *
+ * What actually says "dead surface" is not duration. It is **several gestures
+ * delivered with no pixel moving at all** — one tap that changes nothing is
+ * ordinary, and three in a row are not.
+ */
+export function inputTimes(udid) {
+  try {
+    return fs.readFileSync(paths(udid).lastInput, 'utf8')
+      .split(',')
+      .map(Number)
+      .filter(Number.isFinite);
+  } catch {
+    return [];
+  }
+}
+
+export function lastInputAt(udid) {
+  const times = inputTimes(udid);
+  return times.length ? times[times.length - 1] : null;
+}
+
 export function captureHealth(udid) {
   return readJson(paths(udid).captureHealth);
 }

package/src/supervisor.js

@@ -84,6 +84,18 @@ function backendFor(want) {
  * text — so it broke when the branch grew an else, with nothing actually wrong.
  * A property this important deserves an assertion that runs it.
  */
+/**
+ * The fourth word, and why it is not in `DECISIONS`.
+ *
+ * `abstain` means "I cannot tell from what I was given", and the only correct
+ * thing to do with it is exactly what this module already does with every
+ * failure: return `null`, and behave as if there is no supervisor. So it is a
+ * recognised *answer* and not a recognised *decision*, and keeping those apart
+ * is the point — a caller must never be able to act on it, and a log must be
+ * able to tell it from a timeout, a refusal and a model that was never there.
+ */
+export const ABSTAIN = 'abstain';
+
 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
@@ -113,7 +125,7 @@ export function requested(options) {
  */
 export async function judge({
   goal, step, expected, failure, screen, stillMs, note, options, timeoutMs = 2500,
-  detail,
+  detail, mayAbstain = false,
 } = {}) {
   const want = requested(options);
   if (!want) return null;
@@ -131,6 +143,7 @@ export async function judge({
     screen: (screen ?? []).filter(Boolean).map((s) => String(s).slice(0, 40)).slice(0, 25),
     stillMs: Number.isFinite(stillMs) ? Math.round(stillMs) : null,
     note: note ? String(note).slice(0, 200) : null,
+    mayAbstain: Boolean(mayAbstain),
   }, timeoutMs);
   const decision = decisionOf(answer);
   if (decision == null) {
@@ -144,7 +157,12 @@ export async function judge({
     // 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
+      // An abstention is an answer, and the least interesting thing a log can
+      // say about it is that the supervisor "did not answer". It is the model
+      // declining on purpose, which is the one failure mode worth encouraging.
+      detail.kind = answer?.decision === ABSTAIN
+        ? 'abstained'
+        : answer?.kind
         ?? (answer == null ? 'no answer' : answer.decision ? 'outside the vocabulary' : 'unparseable');
       if (answer?.error) detail.error = String(answer.error).slice(0, 200);
     }