simframe 0.18.0 → 0.19.0

package/src/wedge.js

@@ -21,6 +21,8 @@
 // a job. Nothing here needs a device to be tested.
 import * as api from './index.js';
 import * as frontmost from './frontmost.js';
+import * as input from './input.js';
+import { launchApp, restartDevice } from './platform/index.js';
 
 /**
  * How little agreement between the sensors counts as "these are different
@@ -52,8 +54,39 @@ import * as frontmost from './frontmost.js';
  */
 export const DISAGREEMENT = 0.1;
 
-/** The range observed on healthy screens, for the report to print honestly. */
-export const HEALTHY_FUSION = '0.66-0.93';
+/**
+ * The range observed on healthy screens, for the report to print honestly.
+ *
+ * **Widened 2026-09-18, because the first sample was too narrow and the output
+ * was contradicting itself.** A field reporter watched `diagnose` print
+ * `healthy` twice at **0.567** and **0.615** on the same line as "measured
+ * healthy 0.66-0.93", and was right to call that out: a verdict and the band
+ * printed beside it should not disagree.
+ *
+ * Neither number was wrong. The verdict is correct — the threshold that decides
+ * it is `DISAGREEMENT`, 0.1, and 0.567 is nowhere near it. The *band* was the
+ * wrong thing: it was sampled on five Apple system screens (Settings, General,
+ * About, springboard, Reminders), which are uniformly well-labelled, and a real
+ * third-party app fuses lower because more of its content is OCR-only. Same
+ * afternoon on this device, on system screens: 0.7, 0.846, 0.857 — consistent
+ * with the original sample. The 0.567 and 0.615 come from an app.
+ *
+ * So it is stated as what it is: a range observed across screens, with the floor
+ * from an app rather than from Apple's own UI.
+ *
+ * **And then it was widened once and immediately contradicted again**: the next
+ * device read after that change returned **0.471** on a Settings screen with 34
+ * elements, 25 by tree and 17 by OCR. Which settles what this constant is for.
+ * It is not a health standard — fusion tracks how much of a screen is OCR-only,
+ * that is a property of the app, and any fixed band will be below some real
+ * screen. `diagnose` no longer prints it on the healthy path for that reason.
+ * It survives in the `stale-frame` message, where a reading of 0.03 wants the
+ * contrast, and in `docs/BENCHMARKS.md` as evidence rather than a threshold.
+ *
+ * The number that decides anything is `DISAGREEMENT`, and it is 4.7x below even
+ * the lowest healthy reading yet seen.
+ */
+export const HEALTHY_FUSION = '0.47-0.93';
 
 /**
  * Both sensors need at least this many elements before their disagreement means
@@ -193,6 +226,33 @@ export function classify(snap) {
       revive: true,
     };
   }
+  // One sensor is reading and the other is silent.
+  //
+  // **Found within an hour of shipping this classifier, by it calling a device
+  // `healthy` while the accessibility tree returned nothing at all** — 0 by
+  // tree, 20 by OCR. `agreement` is null unless both sensors report something,
+  // so the disagreement check above cannot fire on this, and nothing else was
+  // looking. A classifier blind to a whole sensor being dead is worse than no
+  // classifier, because it answers.
+  //
+  // It is not cosmetic. CLAUDE.md's perception order makes the tree
+  // authoritative when present, so a silent tree means every intent resolves
+  // against OCR alone — the reading quality a field report called "materially
+  // less reliable" on web content, applied to the whole device, with nothing
+  // saying so.
+  if (total >= ENOUGH_TO_COMPARE && (ax === 0 || ocr === 0)) {
+    const treeDead = ax === 0;
+    return {
+      state: treeDead ? 'tree-silent' : 'ocr-silent',
+      detail: `${treeDead ? 'OCR' : 'the accessibility tree'} found ${Math.max(ax, ocr)} element(s)`
+        + ` and ${treeDead ? 'the accessibility tree' : 'OCR'} found none.`
+        + (treeDead
+          ? ' The tree is authoritative when present, so every intent is now resolving against'
+            + ' OCR alone — materially less reliable, and nothing else says so.'
+          : ' Frames are not being read, so anything that needs pixels is unavailable.'),
+      revive: true,
+    };
+  }
   // An app holds the front, and the display is showing almost nothing. This is
   // the CI signature that `device-state.mjs` recognises as "a clock and nothing
   // else", now stated as an observation. It deliberately does NOT claim to know
@@ -212,7 +272,99 @@ export function classify(snap) {
   return { state: 'healthy', detail: `${total} element(s), sensors agree on ${snap.agreement ?? 'n/a'}`, revive: false };
 }
 
+/**
+ * States that mean the device cannot be driven at all, as opposed to states
+ * that mean it is degraded and should be said out loud.
+ *
+ * The distinction earns its place in `revive`. Demanding `healthy` there turned
+ * a **transient** `tree-silent` into a hard failure and a non-zero exit — and it
+ * is transient: observed surviving a full revive, then clearing after any app
+ * launch, with the springboard reading 13 tree elements again afterwards. A
+ * device whose tree is briefly silent still taps, still reads by OCR, and still
+ * recovers. Failing it is the false-refusal shape of item 175.
+ */
+export const UNUSABLE = new Set(['capture-down', 'nothing-readable', 'read-failed']);
+
 export async function diagnose(deviceQuery, { options } = {}) {
   const snap = await snapshot(deviceQuery, { options });
   return { ...snap, verdict: classify(snap) };
 }
+
+
+/**
+ * How hard a revive looks before calling a device unhealthy.
+ *
+ * A device seconds out of a boot is still settling, and one reading would make
+ * that a false alarm — the failure shape of item 175.
+ */
+export const REVIVE_HEALTH_POLLS = 5;
+export const REVIVE_HEALTH_WAIT_MS = 2000;
+
+/**
+ * What a revive launches to bring a silent accessibility tree back, and the one
+ * platform it makes sense on.
+ *
+ * Settings, because it is on every iOS simulator and opening it changes nothing
+ * a caller could be relying on. The app is incidental — what clears the tree is
+ * that *something* launched. Android is excluded by name rather than by
+ * accident: it has no accessibility tree at all and says so, so `tree-silent`
+ * there is the backend's normal state and not a fault.
+ */
+export const REVIVE_LAUNCH = { ios: 'com.apple.Preferences' };
+
+/**
+ * Power-cycle a device and say what state it came back in.
+ *
+ * The order is load bearing and was learned by hand: stop the daemon, shut the
+ * device down, boot it and *wait for the boot to finish*, start capture, rebuild
+ * the HID session. Any other order leaves a daemon holding a dead device.
+ *
+ * Lifted out of `cli.js` on 2026-09-18 so the bench can use it between passes.
+ * That is not tidying: `bench-hpi` runs `passes x runs` consecutively with no
+ * recovery in between, which on this device is 30 runs against a tolerance of
+ * roughly 8-10, so a three-pass suite has never been physically completable and
+ * the gate has never produced a hosted-runner reading. DEFERRED 173 listed a
+ * revive between passes as worth trying and nothing had tried it.
+ *
+ * `onStep` is called with each step's outcome so a CLI can print it live and a
+ * script can stay quiet.
+ */
+export async function revive(deviceQuery, { options, onStep = () => {}, device } = {}) {
+  const dev = device ?? { udid: String(deviceQuery), name: String(deviceQuery), platform: 'ios' };
+  const steps = [];
+  const did = async (what, fn) => {
+    try {
+      await fn();
+      steps.push({ step: what, ok: true });
+      onStep({ step: what, ok: true });
+    } catch (err) {
+      steps.push({ step: what, ok: false, error: err.message });
+      onStep({ step: what, ok: false, error: err.message });
+    }
+  };
+  // Forced: the point of this is that the device is wedged, so something is
+  // certainly still holding it.
+  await did('stopped the daemon', async () => { api.stopDaemon(dev.udid, { force: true }); });
+  await did('restarted the device, and waited for the boot to finish', () => restartDevice(dev.udid));
+  await did('started capture', () => api.ensureDaemon(dev.udid));
+  await did('rebuilt the HID session', () => input.resetSession(dev.udid));
+
+  let verdict = null;
+  for (let attempt = 0; attempt < REVIVE_HEALTH_POLLS; attempt += 1) {
+    verdict = classify(await snapshot(dev.udid, { options }).catch(() => null));
+    if (verdict?.state === 'healthy') break;
+    if (attempt < REVIVE_HEALTH_POLLS - 1) await new Promise((r) => setTimeout(r, REVIVE_HEALTH_WAIT_MS));
+  }
+  // A silent tree does not heal with time and does heal with a launch — six
+  // reads over 60s at 0 elements, then 14 immediately after one launch.
+  const bundle = REVIVE_LAUNCH[dev.platform];
+  if (verdict?.state === 'tree-silent' && bundle) {
+    await did('launched an app, which is what brings a silent tree back', async () => {
+      await launchApp(dev.udid, bundle, { args: [], env: {} });
+      await new Promise((r) => setTimeout(r, REVIVE_HEALTH_WAIT_MS));
+    });
+    verdict = classify(await snapshot(dev.udid, { options }).catch(() => null)) ?? verdict;
+  }
+  const state = verdict?.state ?? 'read-failed';
+  return { device: dev, steps, verdict, state, usable: !UNUSABLE.has(state), healthy: state === 'healthy' };
+}