simframe 0.17.0 → 0.19.0

package/src/metrics.js

@@ -12,6 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import * as store from './store.js';
+import { deviceCause } from './device-state.js';
 
 /** The five reasons, from docs/research/03-human-parity.md §8. Nothing else is a reason. */
 export const REASONS = [
@@ -66,6 +67,52 @@ export const FACULTY = {
  */
 export const BUILT_FACULTIES = new Set(['sense of time (Phase 11)']);
 
+/**
+ * The faculty a `verification_failed` record points at, by **verdict**.
+ *
+ * `FACULTY` is keyed on the reason, and for this class the reason is too coarse
+ * to steer by. Measured on the bench device's 1022 records: of the
+ * `verification_failed` ones, 162 are `no-visible-change`, 26 are
+ * `unexpected-screen`, and about 172 are a wait that timed out — three
+ * different faculties, all of which the report named as "sense of time
+ * (Phase 11)" because that is what the reason maps to.
+ *
+ * `unexpected-screen` is the clearest case: it is item 174, screen identity
+ * fragmenting on content-driven screens, and reporting it as a timing problem
+ * is how a tester was once told their unlabeled-control problem was a timing
+ * problem.
+ */
+/**
+ * The verdict a legacy record carries in the first token of its `detail`.
+ *
+ * Written as `${verdict}: ${detail}` since the field existed, so the prefix is
+ * reliable — but only for records whose detail came from a verdict at all,
+ * which is why this returns null rather than guessing on anything else.
+ */
+export function verdictFromDetail(detail) {
+  const m = /^([a-z][a-z-]{3,30}):\s/.exec(String(detail ?? ''));
+  // Only a verdict that exists. The first draft returned any lowercase prefix
+  // and duly reported a verdict called **"capture"** with a count of 8, from
+  // details reading `capture: ...`. A parser that invents a category gets it
+  // counted, named in a report, and eventually used to choose a phase — which
+  // is the whole failure this grouping was added to fix, reproduced inside the
+  // fix.
+  return m && KNOWN_VERDICTS.has(m[1]) ? m[1] : null;
+}
+
+export const VERDICT_FACULTY = {
+  'unexpected-screen': 'screen identity (item 174)',
+  'still-filling-in': 'sense of time (Phase 11)',
+  // **`no-visible-change` is deliberately absent, and it is the largest verdict
+  // in the log (162 of 1022).** The escalation site has a measured argument for
+  // leaving it unclassified and it is right: in the field it came
+  // overwhelmingly from tapping an inert text label whose real hit target was
+  // an invisible chevron — icon semantics, Phase 15 — but it also covers a
+  // switch moving 0.1% of the screen, which is neither faculty. Two causes, one
+  // verdict, and no way to tell them apart from here. Putting it in this map
+  // would name a faculty for 162 records on a coin flip.
+};
+
 function metricPaths(udid) {
   const dir = store.deviceDir(udid);
   return {
@@ -323,6 +370,17 @@ export function reasonForStepError(step, err) {
   // admits "other" collects a pile of "other". What changes is that the record
   // carries whether the reason was *read off the failure* or *assumed*, and
   // the report declines to recommend a faculty for the assumed ones.
+  // The device, not a faculty.
+  //
+  // 78 of this class on the bench device are `xcrun simctl openurl` failing, an
+  // app that would not launch, or capture stopping. Those are item 173, and
+  // filing them under a code faculty is how the log came to offer "sense of
+  // time (Phase 11)" as the remedy for a simulator that had stopped answering.
+  // `classified` stays false because no *faculty* was read; `device` says what
+  // was, so the report can take these out of the faculty count instead of
+  // counting them towards a phase.
+  const device = deviceCause(err?.message);
+  if (device) return { reason: 'verification_failed', candidates: [], tried: [], classified: false, device };
   return { reason: 'verification_failed', candidates: [], tried: [], classified: false };
 }
 
@@ -336,6 +394,17 @@ export function reasonForStepError(step, err) {
  */
 export const ESCALATING_VERDICTS = new Set(['unexpected-screen', 'no-visible-change']);
 
+/**
+ * Every verdict the engine can report, for reading legacy details back.
+ *
+ * Wider than `ESCALATING_VERDICTS` — which is the two that hand back to a model
+ * — because a record's detail may carry any of them, and narrower than "any
+ * lowercase word", which is what a prefix parser accepts if nobody bounds it.
+ */
+export const KNOWN_VERDICTS = new Set([
+  'unexpected-screen', 'no-visible-change', 'still-filling-in', 'unverified', 'ok',
+]);
+
 /** How `goto`/`flow run` refusals map. They refuse rather than guess, and the refusal is the hand-back. */
 export const PLAN_REASONS = {
   'unknown-screen': 'unknown_screen',
@@ -463,6 +532,14 @@ export function recordEscalation(udid, {
   // Default `false`, so a caller that does not think about it cannot
   // accidentally claim precision it does not have.
   classified = false,
+  // Which device-state condition this failure shows, when it shows one. Kept
+  // separate from `reason` because the five-reason vocabulary is fixed and a
+  // sixth reason collects a pile of "other" — see REASONS.
+  device = null,
+  // Which local verdict fired, for the records that have one. Derivable from
+  // `detail` today by parsing a prefix, which is exactly the fragility the log
+  // should not depend on.
+  verdict = null,
 } = {}) {
   if (!REASONS.includes(reason)) throw new Error(`not an escalation reason: ${reason}`);
   if (!OUTCOMES.includes(outcome)) throw new Error(`not an escalation outcome: ${outcome}`);
@@ -479,6 +556,10 @@ export function recordEscalation(udid, {
     // go/no-go, and on its own it answers "what kind of decision is costing us".
     intent: intent ? String(intent).slice(0, 120) : null,
     classified: Boolean(classified),
+    // Null unless read. Both of these separate "we know" from "we assumed" for
+    // a class that is otherwise one coarse bucket.
+    device_cause: device ? String(device).slice(0, 120) : null,
+    verdict: verdict ? String(verdict).slice(0, 60) : null,
     step_index: stepIndex,
     screen_fingerprint: fingerprint,
     reason,
@@ -538,7 +619,9 @@ export function flowRecordFrom({
     images_sent: imagesSent,
     input_tokens: null,
     output_tokens: null,
-    escalations: escalations.map((e) => ({ reason: e.reason, step_index: e.step_index, outcome: e.outcome })),
+    escalations: escalations.map((e) => ({
+      reason: e.reason, step_index: e.step_index, outcome: e.outcome, device_cause: e.device_cause ?? null,
+    })),
     escalation_count: escalations.length,
     mis_taps: misTaps,
     verdict_histogram: histogram,
@@ -546,6 +629,22 @@ export function flowRecordFrom({
     exploration_events: [],
     completed: Boolean(completed),
     wrong_action_taken: verdicts.includes('unexpected-screen'),
+    // Did this run fail because the *simulator* failed?
+    //
+    // Measured, on a full local suite: of 17 runs, 5 failed because the guest's
+    // SpringBoard crashed or `simctl` stopped answering for 90 s. `hpi`
+    // counted every one against `HPI_accuracy`, so the gate CI reads was partly
+    // measuring SpringBoard's stability.
+    //
+    // This is item 172 in the other column. There, `HPI_time` took every run's
+    // wall clock regardless of completion, so breaking a flow registered as the
+    // agent getting quicker; the fix was to time only completed runs. Accuracy
+    // had the mirror-image fault and kept it.
+    //
+    // Derived from the escalations this run already wrote — `device_cause` is
+    // set at the step that suffered it — so nothing new has to be plumbed and a
+    // run cannot claim a device fault that its own log does not show.
+    device_cause: escalations.map((e) => e.device_cause).find(Boolean) ?? null,
   };
 }
 
@@ -691,8 +790,14 @@ export function hpi({ flows, baselines = {} }) {
     };
   }).sort((a, b) => a.flow.localeCompare(b.flow));
 
-  const total = flows.length;
-  const clean = flows.filter((f) => f.completed && !f.wrong_action_taken).length;
+  // A run the simulator broke is not a run the code got wrong. It is an
+  // **unmeasured** run, and it leaves the denominator rather than lowering the
+  // score — the same discipline as timing only completed runs (172), and the
+  // same discipline as the suite refusing to publish a partial HPI at all.
+  const lostToDevice = flows.filter((f) => f.device_cause && !f.completed);
+  const measurable = flows.filter((f) => !(f.device_cause && !f.completed));
+  const total = measurable.length;
+  const clean = measurable.filter((f) => f.completed && !f.wrong_action_taken).length;
   const accuracy = total ? Number((clean / total).toFixed(3)) : null;
   const times = perFlow.map((f) => f.hpi_time).filter((x) => Number.isFinite(x));
   const hpiTime = harmonicMean(times);
@@ -700,6 +805,11 @@ export function hpi({ flows, baselines = {} }) {
     flows: perFlow,
     overall: {
       runs: total,
+      // Said out loud, because a denominator that quietly shrinks is worse than
+      // one that is wrong: an accuracy of 1.0 over two measurable runs is not
+      // the same claim as 1.0 over eighteen.
+      runs_lost_to_device: lostToDevice.length,
+      device_causes: [...new Set(lostToDevice.map((f) => f.device_cause))],
       flows_measured: perFlow.length,
       flows_with_human_baseline: times.length,
       hpi_accuracy: accuracy,
@@ -728,12 +838,20 @@ export function breakdown(records, { session = null, flow = null } = {}) {
   const classifiedByReason = {};
   const assumedByReason = {};
   for (const r of REASONS) { byReason[r] = 0; classifiedByReason[r] = 0; assumedByReason[r] = 0; }
+  // Two more groupings, because the reason alone could not steer. `byVerdict`
+  // splits the largest class into the three different things it holds, and
+  // `byDevice` takes out the records that are the simulator rather than the
+  // code — those were being counted towards a perception phase.
+  const byVerdict = new Map();
+  const byDevice = new Map();
   const byScreen = new Map();
   const byOutcome = {};
   const bySession = new Map();
   const byFlow = new Map();
   let avoidable = 0;
   let unattributed = 0;
+  let derivedVerdicts = 0;
+  let derivedDevice = 0;
   // Filtering happens here rather than at the call site so `total` and every
   // rate below it describe the same set of records.
   const kept = records.filter((r) => (session ? r?.session_id === session : true))
@@ -757,6 +875,18 @@ export function breakdown(records, { session = null, flow = null } = {}) {
     // real one gets ignored, which this file already knows in another place.
     if (r.classified === true) classifiedByReason[r.reason] += 1;
     else if (r.classified === false) assumedByReason[r.reason] += 1;
+    // Derived for the records that predate the fields, rather than waiting for
+    // a fresh corpus. `detail` already carries both facts — the verdict as its
+    // prefix, the device signature inside the message — so a read-time
+    // derivation turns 1022 existing records into signal without rewriting a
+    // single line of the log. Marked in the output as derived, because a
+    // recorded fact and a parsed one are not the same evidence.
+    const verdict = r.verdict ?? verdictFromDetail(r.detail);
+    const device = r.device_cause ?? deviceCause(r.detail);
+    if (verdict) byVerdict.set(verdict, (byVerdict.get(verdict) ?? 0) + 1);
+    if (device) byDevice.set(device, (byDevice.get(device) ?? 0) + 1);
+    if (!r.verdict && verdict) derivedVerdicts += 1;
+    if (!r.device_cause && device) derivedDevice += 1;
     byOutcome[r.outcome] = (byOutcome[r.outcome] ?? 0) + 1;
     // Already avoided locally, so not avoidable by anything unbuilt.
     if (r.outcome !== 'resolved_locally') avoidable += 1;
@@ -770,8 +900,19 @@ export function breakdown(records, { session = null, flow = null } = {}) {
       return { session_id: id, client, count };
     })
     .sort((a, b) => b.count - a.count);
+  const sorted = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]).map(([name, count]) => ({ name, count }));
   return {
     total,
+    // What the reason could not say. `verdicts` is the largest class split into
+    // the faculties it actually implies; `device` is the part that is item 173
+    // wearing a code reason.
+    verdicts: sorted(byVerdict),
+    device: sorted(byDevice),
+    device_total: [...byDevice.values()].reduce((a, b) => a + b, 0),
+    // How much of the two groupings above was parsed out of `detail` rather
+    // than recorded at the time. A reader deciding a phase order should know
+    // which half they are looking at.
+    derived: { verdicts: derivedVerdicts, device: derivedDevice },
     // The log is per-device and shared: two agents on one booted simulator
     // write one interleaved file. More than one session here means the counts
     // below are a pool, and CLAUDE.md uses those counts to choose a phase.

package/src/navigate.js

@@ -47,6 +47,16 @@ function refuse(udid, result, { detail = null, flowName = null } = {}) {
     if (reason) {
       metrics.recordEscalation(udid, {
         reason,
+        // Read, not assumed. `recordEscalation` defaults `classified` to false
+        // so a careless caller cannot claim precision it does not have, which
+        // is right — and this caller is not careless: `result.reason` is a
+        // named refusal (`no-route`, `unreplayable-edge`, `unknown-flow`,
+        // `arrived-elsewhere`…) and PLAN_REASONS maps it deterministically.
+        // Saying nothing filed 82 records on the bench device as "reason
+        // assumed" when the reason was known exactly, which makes the log
+        // understate its own knowledge and the report decline to name a
+        // faculty it was entitled to name.
+        classified: true,
         // A refusal by `goto` is about a destination and one by `flow run` is
         // about a named flow. Either is what a breakdown wants to group by.
         flowName,

package/src/platform/cdp.js

@@ -0,0 +1,242 @@
+// A dependency-free Chrome DevTools Protocol client.
+//
+// Hand-rolled rather than `ws`, and not because of ideology: CLAUDE.md keeps
+// the runtime dependency list at exactly one (the MCP SDK), and the alternative
+// does not exist anyway. The global `WebSocket` is **absent on Node 18 and
+// flag-only on Node 20** — verified here on v20.20.0, where `typeof WebSocket`
+// is `undefined` — and this package supports 18, 20 and 22. So the choice is
+// between a dependency and forty lines of RFC 6455, and forty lines is smaller
+// than the surface a dependency brings.
+//
+// The other thing a probe on 2026-09-11 established, recorded because it costs
+// an afternoon to rediscover: Chrome refuses the upgrade with **401
+// Unauthorized** when an `Origin` header is present and does not match the
+// inspector's own host. A browser's own WebSocket API always sends one and
+// cannot change it, which is why a page cannot drive CDP — and why a
+// hand-rolled client, which simply omits the header, can.
+//
+// Scope: enough CDP to be the transport under `src/platform/web.js`. It speaks
+// one target at a time, it does not multiplex sessions, and it has no
+// reconnection policy. Anything cleverer belongs above the boundary or nowhere.
+import net from 'node:net';
+import crypto from 'node:crypto';
+import http from 'node:http';
+
+/** RFC 6455's fixed GUID, concatenated with the client key to prove the handshake. */
+export const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+const OPCODE = { text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa };
+
+/** Ask a browser what it has open. `targetId` is the udid: a tab is a device. */
+export function listTargets(port, host = '127.0.0.1', { timeoutMs = 2000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ host, port, path: '/json/list', timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (d) => { body += d; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`the browser's debugging endpoint answered ${res.statusCode} — is it running with --remote-debugging-port=${port}?`));
+          return;
+        }
+        try { resolve(JSON.parse(body)); } catch (err) { reject(new Error(`the debugging endpoint returned something that is not JSON: ${err.message}`)); }
+      });
+    });
+    req.on('timeout', () => { req.destroy(new Error(`no answer from ${host}:${port} within ${timeoutMs}ms`)); });
+    req.on('error', (err) => reject(new Error(
+      `cannot reach a browser on ${host}:${port} — ${err.message}.`
+      + ' Start one with --remote-debugging-port, or pass --port.',
+    )));
+  });
+}
+
+/**
+ * One frame, encoded.
+ *
+ * Client frames must be masked — an unmasked client frame is a protocol error
+ * and Chrome closes the socket rather than answering, which reads as a hang.
+ */
+function encodeFrame(payload, opcode = OPCODE.text) {
+  const data = Buffer.from(payload, 'utf8');
+  const mask = crypto.randomBytes(4);
+  const len = data.length;
+  const header = len < 126
+    ? Buffer.from([0x80 | opcode, 0x80 | len])
+    : len < 65536
+      ? Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 126]), (() => { const b = Buffer.alloc(2); b.writeUInt16BE(len); return b; })()])
+      : Buffer.concat([Buffer.from([0x80 | opcode, 0x80 | 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(len)); return b; })()]);
+  const masked = Buffer.allocUnsafe(len);
+  for (let i = 0; i < len; i += 1) masked[i] = data[i] ^ mask[i % 4];
+  return Buffer.concat([header, mask, masked]);
+}
+
+/**
+ * Pull whole frames out of a growing buffer.
+ *
+ * Returns the frames it could complete and what is left over. CDP replies
+ * routinely exceed one TCP segment — a full accessibility tree is tens of
+ * kilobytes — so a reader that assumes one frame per `data` event works on a
+ * hello-world and fails on the first real payload.
+ */
+export function decodeFrames(buffer) {
+  const frames = [];
+  let rest = buffer;
+  for (;;) {
+    if (rest.length < 2) break;
+    const opcode = rest[0] & 0x0f;
+    const fin = Boolean(rest[0] & 0x80);
+    const masked = Boolean(rest[1] & 0x80);
+    let len = rest[1] & 0x7f;
+    let offset = 2;
+    if (len === 126) {
+      if (rest.length < 4) break;
+      len = rest.readUInt16BE(2);
+      offset = 4;
+    } else if (len === 127) {
+      if (rest.length < 10) break;
+      len = Number(rest.readBigUInt64BE(2));
+      offset = 10;
+    }
+    const maskKey = masked ? rest.subarray(offset, offset + 4) : null;
+    if (masked) offset += 4;
+    if (rest.length < offset + len) break;
+    let payload = rest.subarray(offset, offset + len);
+    if (maskKey) {
+      const out = Buffer.allocUnsafe(len);
+      for (let i = 0; i < len; i += 1) out[i] = payload[i] ^ maskKey[i % 4];
+      payload = out;
+    }
+    frames.push({ opcode, fin, payload });
+    rest = rest.subarray(offset + len);
+  }
+  return { frames, rest };
+}
+
+/**
+ * Open a CDP session against a websocket URL from `listTargets`.
+ *
+ * Resolves once the upgrade is accepted, so a caller that gets a connection has
+ * a usable one — the failure mode this avoids is a `send` that queues silently
+ * against a socket the browser refused.
+ */
+export function connect(wsUrl, { timeoutMs = 5000 } = {}) {
+  const url = new URL(wsUrl);
+  return new Promise((resolve, reject) => {
+    const key = crypto.randomBytes(16).toString('base64');
+    const socket = net.connect({ host: url.hostname, port: Number(url.port || 80) });
+    let settled = false;
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(err);
+    };
+    const timer = setTimeout(() => fail(new Error(`the browser did not complete the websocket upgrade within ${timeoutMs}ms`)), timeoutMs);
+
+    socket.on('error', (err) => fail(new Error(`cannot open a debugging socket: ${err.message}`)));
+    socket.on('connect', () => {
+      // No `Origin` header, deliberately. Chrome answers 401 when one is
+      // present and does not match the inspector's host, and nothing here needs
+      // to claim an origin.
+      socket.write(
+        `GET ${url.pathname}${url.search} HTTP/1.1\r\n`
+        + `Host: ${url.host}\r\n`
+        + 'Upgrade: websocket\r\nConnection: Upgrade\r\n'
+        + `Sec-WebSocket-Key: ${key}\r\n`
+        + 'Sec-WebSocket-Version: 13\r\n\r\n',
+      );
+    });
+
+    let handshake = Buffer.alloc(0);
+    const onHandshake = (chunk) => {
+      handshake = Buffer.concat([handshake, chunk]);
+      const end = handshake.indexOf('\r\n\r\n');
+      if (end === -1) return;
+      const head = handshake.subarray(0, end).toString('latin1');
+      const status = /^HTTP\/1\.1 (\d+)/.exec(head)?.[1];
+      if (status !== '101') {
+        fail(new Error(
+          `the browser refused the debugging socket with HTTP ${status ?? '(no status)'}.`
+          + (status === '401'
+            ? ' That is the Origin check: Chrome rejects an upgrade whose Origin header does not'
+              + ' match the inspector host. This client sends none, so something else set one.'
+            : ' Check the target still exists — a closed tab keeps its id but not its socket.'),
+        ));
+        return;
+      }
+      const accept = /sec-websocket-accept:\s*(\S+)/i.exec(head)?.[1];
+      const expected = crypto.createHash('sha1').update(key + WS_GUID).digest('base64');
+      if (accept !== expected) {
+        fail(new Error('the browser accepted the upgrade with a key that does not match — this is not a websocket peer'));
+        return;
+      }
+      clearTimeout(timer);
+      settled = true;
+      socket.removeListener('data', onHandshake);
+      resolve(session(socket, handshake.subarray(end + 4)));
+    };
+    socket.on('data', onHandshake);
+  });
+}
+
+/** A connected session: one id space, one pending map, text frames only. */
+function session(socket, leftover) {
+  let buffer = leftover ?? Buffer.alloc(0);
+  let nextId = 1;
+  let closedWith = null;
+  const pending = new Map();
+  const listeners = new Set();
+
+  const rejectAll = (err) => {
+    for (const { reject } of pending.values()) reject(err);
+    pending.clear();
+  };
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    const { frames, rest } = decodeFrames(buffer);
+    buffer = rest;
+    for (const frame of frames) {
+      if (frame.opcode === OPCODE.ping) { socket.write(encodeFrame(frame.payload.toString('utf8'), OPCODE.pong)); continue; }
+      if (frame.opcode === OPCODE.close) { closedWith = 'the browser closed the debugging socket'; socket.end(); continue; }
+      if (frame.opcode !== OPCODE.text) continue;
+      let message;
+      try { message = JSON.parse(frame.payload.toString('utf8')); } catch { continue; }
+      if (message.id != null && pending.has(message.id)) {
+        const { resolve, reject } = pending.get(message.id);
+        pending.delete(message.id);
+        // A CDP error is a reply, not a transport failure, and it carries the
+        // only sentence that says what was wrong with the call.
+        if (message.error) reject(new Error(`${message.error.message ?? 'CDP error'}${message.error.data ? ` — ${message.error.data}` : ''}`));
+        else resolve(message.result ?? {});
+      } else if (message.method) {
+        for (const fn of listeners) { try { fn(message); } catch { /* a listener must not break the socket */ } }
+      }
+    }
+  });
+
+  socket.on('close', () => { rejectAll(new Error(closedWith ?? 'the debugging socket closed')); });
+  socket.on('error', (err) => { rejectAll(new Error(`debugging socket error: ${err.message}`)); });
+
+  return {
+    /** One CDP call. Rejects with the browser's own message on a protocol error. */
+    send(method, params = {}, { timeoutMs = 10000 } = {}) {
+      if (socket.destroyed) return Promise.reject(new Error(closedWith ?? 'the debugging socket is closed'));
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`${method} did not answer within ${timeoutMs}ms`));
+        }, timeoutMs);
+        pending.set(id, {
+          resolve: (v) => { clearTimeout(timer); resolve(v); },
+          reject: (e) => { clearTimeout(timer); reject(e); },
+        });
+        socket.write(encodeFrame(JSON.stringify({ id, method, params })));
+      });
+    },
+    /** Subscribe to CDP events. Returns an unsubscribe. */
+    on(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    close() { try { socket.end(encodeFrame('', OPCODE.close)); } catch { socket.destroy(); } },
+    get closed() { return socket.destroyed; },
+  };
+}

package/src/platform/index.js

@@ -20,6 +20,7 @@
 // function that takes a udid routes on that udid — `ownsUdid` answers that from
 // the id's own shape, because the question is asked from inside a capture loop
 // in a process that never listed anything.
+import * as store from '../store.js';
 import { platform as android } from './android.js';
 import { platform as ios } from './ios.js';
 
@@ -204,9 +205,34 @@ export async function resolveAcross(query, opts, all) {
 // backend a call reaches, never what the call means.
 export const isBootedSync = (udid, ...args) => platformFor(udid).isBootedSync(udid, ...args);
 export const screenshot = (udid, ...args) => platformFor(udid).screenshot(udid, ...args);
-export const launchApp = (udid, ...args) => platformFor(udid).launchApp(udid, ...args);
+/**
+ * Launch and openUrl stamp the action clock; nothing else here does.
+ *
+ * These two change the screen without touching the digitizer, so they are the
+ * only actions a gesture log cannot see — and a settle that cannot see them
+ * measures how long the screen being *left* has been sitting still. Measured:
+ * 283ms after a Settings launch, `settled: true` with `stableForMs: 4427` over
+ * a screen holding zero elements.
+ *
+ * **At the seam rather than in the `launch` step, and that placement is the
+ * point.** It was in the step first, which covered flows and missed everything
+ * else that launches an app — `baseline.resetFor`, `wedge.revive`, the bench,
+ * and the probe that found this. A rule enforced where you noticed it covers a
+ * symptom; this project's handoff has three worked examples of exactly that and
+ * this was very nearly a fourth.
+ *
+ * `terminateApp` is deliberately not stamped: it removes an app rather than
+ * presenting one, and the screen it leaves behind is whatever was underneath.
+ */
+export const launchApp = (udid, ...args) => {
+  store.noteAction(udid);
+  return platformFor(udid).launchApp(udid, ...args);
+};
 export const terminateApp = (udid, ...args) => platformFor(udid).terminateApp(udid, ...args);
-export const openUrl = (udid, ...args) => platformFor(udid).openUrl(udid, ...args);
+export const openUrl = (udid, ...args) => {
+  store.noteAction(udid);
+  return platformFor(udid).openUrl(udid, ...args);
+};
 export const setPermission = (udid, ...args) => platformFor(udid).setPermission(udid, ...args);
 export const setPasteboard = (udid, ...args) => platformFor(udid).setPasteboard(udid, ...args);
 

package/src/store.js

@@ -35,6 +35,7 @@ export function paths(udid) {
     // recorded, and a stall is the absence of frames.
     captureHealth: path.join(dir, 'capture-health.json'),
     lastInput: path.join(dir, 'last-input'),
+    lastAction: path.join(dir, 'last-action'),
   };
 }
 
@@ -58,6 +59,44 @@ export function noteInput(udid, at = Date.now()) {
   } catch {
     /* a timestamp nothing depends on for correctness must not fail an action */
   }
+  noteAction(udid, at);
+}
+
+/**
+ * When we last did something that ought to change the screen.
+ *
+ * Deliberately separate from the input log above, which answers a different
+ * question — "have several *gestures* landed with no pixel moving" — and would
+ * be wrong to answer it about a launch, since a launch that paints nothing is
+ * not evidence of a dead digitizer.
+ *
+ * This one exists so a settle can tell its own stillness from the *previous*
+ * screen's. Measured on 2026-09-18: 283ms after a Settings launch the state
+ * read `settled: true` with `stableForMs: 4427` and **zero elements** — 4.4
+ * seconds of quiet that began before the launch was issued. 408ms after a
+ * `tap General`, `stableForMs: 7753` and the 23 elements of the screen being
+ * left. In both, the settle detector was honestly reporting how long the screen
+ * we had already abandoned had been sitting still.
+ *
+ * Every gesture writes it (via `noteInput`), and so does every launch and
+ * `openUrl`, because those change the screen without touching the digitizer.
+ */
+export function noteAction(udid, at = Date.now()) {
+  try {
+    writeAtomic(paths(udid).lastAction, String(at));
+  } catch {
+    /* as above: a timestamp may not fail the action it describes */
+  }
+}
+
+/** When the last screen-changing action was issued, or null if none is recorded. */
+export function lastActionAt(udid) {
+  try {
+    const n = Number(fs.readFileSync(paths(udid).lastAction, 'utf8').trim());
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
 }
 
 /**