simframe 0.11.0 → 0.12.0

package/scripts/collect-rulings.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+// Generate a population of supervisor rulings, and score them.
+//
+// Items 101, 96, 106 and 109a all need rulings to replay, and the log held one,
+// because a ruling requires a step that genuinely fails and Apple's own apps do
+// not fail on command. The React Native testbed does, from a seeded stream, so
+// this turns "we need dozens of rulings" into a script.
+//
+// Every fixture here has a **known correct outcome**, which is what makes the
+// population scoreable rather than merely large:
+//
+//   arriving  a list still loading. Re-running the step works, so the right
+//             answer is wait/retry and the right outcome is `recovered`.
+//   blocked   a required field is empty, so the thing waited for can never
+//             appear. Waiting and retrying are both wrong; `stopped` is right.
+//   refused   a submit that failed. Re-running the *wait* cannot help — only
+//             re-submitting could, and that is the planner's call, not the
+//             supervisor's — so `stopped` is right here too.
+//
+// Note `refused` and `blocked` want the same answer for different reasons. That
+// is deliberate: a judge that says stop for the wrong reason is still right, and
+// a population that only contains obvious cases measures nothing.
+//
+//   SIMFRAME_SUPERVISOR=apple node scripts/collect-rulings.mjs --device=<udid> --seeds=8
+import { execFile } from 'node:child_process';
+import * as actions from '../src/actions.js';
+import * as api from '../src/index.js';
+import * as metrics from '../src/metrics.js';
+import * as store from '../src/store.js';
+import * as supervisor from '../src/supervisor.js';
+
+const arg = (name, fallback) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : fallback;
+};
+const device = arg('device');
+const seeds = Number(arg('seeds', 6));
+const BUNDLE = 'com.example.simframetestbed';
+
+if (!supervisor.requested({})) {
+  console.error('SIMFRAME_SUPERVISOR is not set, so nothing would be judged and no ruling would be recorded.');
+  process.exit(2);
+}
+
+// Before anything else, because the device may already be wedged from the last
+// run — `ensureDaemon` throws on a display that has stopped rendering, and it
+// threw here on the third attempt of the afternoon, before the loop's own check
+// could ever run. Driving one simulator hard for a few minutes is what does it.
+{
+  const { execFileSync } = await import('node:child_process');
+  try {
+    await api.ensureDaemon(device);
+  } catch {
+    console.log('the device is not producing frames; reviving before starting');
+    try {
+      execFileSync(process.execPath, ['src/cli.js', 'revive', `--device=${device}`],
+        { cwd: new URL('..', import.meta.url).pathname, timeout: 300_000, stdio: 'inherit' });
+    } catch { /* reported below by the throw from ensureDaemon */ }
+  }
+}
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})`);
+
+/**
+ * Cold-launch the app with a seed.
+ *
+ * `openUrl` on a terminated app launches it with that URL as its initial URL,
+ * which is the only way to set the seed *before* the first screen mounts and
+ * starts its own timers. Relaunching and then opening the URL would be too
+ * late: the list's delay has already been drawn from the default stream.
+ */
+/**
+ * Scaffolding runs with the supervisor OFF, and that is not a detail.
+ *
+ * The first collection run produced 18 rulings of which **14 came from the
+ * harness's own plumbing** — seven from tapping an "Open in …?" dialog that was
+ * not always there, two from terminating an app that was not running, three
+ * from typing into a form we had failed to reach. Every one was a real
+ * consultation and every one would have landed in the population that 101 and
+ * 96 are going to measure.
+ *
+ * A fixture is a claim about what the supervisor should say. Plumbing is not,
+ * and a harness that cannot tell them apart is measuring itself.
+ */
+const SCAFFOLD = { supervisor: 'none' };
+
+const launchSeeded = async (seed) => {
+  // Terminating an app that is not running fails, and a failed step aborts the
+  // rest of the batch — so it gets its own call and its own shrug.
+  await actions.runScript(device, { steps: [{ terminate: BUNDLE }], verify: false, options: SCAFFOLD }).catch(() => null);
+  await actions.runScript(device, {
+    steps: [{ openUrl: `simframetestbed://seed/${seed}` }, { pause: 1200 }],
+    verify: false,
+    options: SCAFFOLD,
+  });
+  // iOS asks "Open in ...?" whenever a custom scheme is opened by another
+  // process, springboard included, and it asks on every launch. Answered here
+  // rather than designed around: the alternative is launch arguments, which RN
+  // does not expose to JavaScript without a native module.
+  await actions.runScript(device, {
+    steps: [{ tap: 'Open' }, { pause: 2200 }],
+    verify: false,
+    options: SCAFFOLD,
+  }).catch(async () => {
+    // No dialog this time. Give the app the same settling time anyway, so the
+    // fixture's timing does not depend on whether iOS felt like asking.
+    await actions.runScript(device, { steps: [{ pause: 2200 }], verify: false, options: SCAFFOLD }).catch(() => null);
+  });
+};
+
+/**
+ * Walk to where a fixture starts, unjudged — and *prove* you arrived.
+ *
+ * Navigation is scaffolding too. Three of the first run's stray rulings were a
+ * `type` that failed because the form had never been reached.
+ *
+ * The `arrive` half is the harder lesson, and it cost a wrong number. A walk
+ * that does not throw is not a walk that arrived: two `Next` taps landed on a
+ * live button, threw nothing, and advanced nothing, so **three of four rulings
+ * in the first clean run were taken on step 1 of a three-step form** while the
+ * fixture claimed they were about the review step. The scoreboard read 25% and
+ * was measuring the harness.
+ *
+ * `eval-fingerprint.mjs` already learned exactly this — it checks that each
+ * reading was taken on the screen the tour named, having once measured a
+ * distribution against readings taken somewhere else. The check simply had not
+ * been carried over.
+ */
+const walk = async (steps, arrive) => {
+  try {
+    if (steps.length) await actions.runScript(device, { steps, verify: false, options: SCAFFOLD });
+    if (!arrive) return true;
+    // Asserted, not assumed. An assert that throws means we are not there.
+    await actions.runScript(device, {
+      steps: [{ assert: { value: arrive, is: 'visible' } }],
+      verify: false,
+      options: SCAFFOLD,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Revive the device if capture has given up, and keep going.
+ *
+ * Collecting a population means driving one simulator hard for several minutes,
+ * and the display stops rendering when you do — twice in one afternoon here. The
+ * daemon detects it, tries both its recoveries, reports `stalled` and stops,
+ * because a capture loop that rebooted the device it was watching would be a
+ * tool reaching for the mains. This is a harness, not the product, and the
+ * operator's answer is exactly what it is here to automate — otherwise a run of
+ * twenty fixtures ends at the third and the population is however many rulings
+ * the device survived.
+ */
+const reviveIfWedged = async () => {
+  const health = store.captureHealth(dev.udid);
+  if (!health?.stalled) return false;
+  process.stdout.write('  (capture stalled — reviving the device before continuing)\n');
+  await new Promise((resolve) => {
+    execFile(process.execPath, ['src/cli.js', 'revive', `--device=${dev.udid}`],
+      { timeout: 300_000, cwd: new URL('..', import.meta.url).pathname }, () => resolve());
+  });
+  return true;
+};
+
+const FIXTURES = [
+  {
+    name: 'arriving',
+    want: 'recovered',
+    // Pull to refresh rather than relying on the launch, because reaching the
+    // fixture now takes three seconds of its own — answering iOS's "Open in …?"
+    // — and by then the list has always arrived. The first clean run produced
+    // *no rulings at all* from this fixture for that reason. A refresh empties
+    // the list and reloads it on a fresh seeded delay, right where we want it.
+    walk: [{ swipe: { from: [201, 300], to: [201, 620] } }],
+    arrive: null,
+    judge: { waitFor: { value: 'Monstera #1', timeoutMs: 700 } },
+    expect: 'the list is still loading; its rows arrive shortly after launch',
+  },
+  {
+    name: 'detail',
+    want: 'recovered',
+    // A detail screen that is still fetching. Waiting is the right answer and
+    // re-running the step proves it, which is what makes this scoreable.
+    walk: [{ tap: 'Monstera #1' }],
+    arrive: null,
+    judge: { waitFor: { value: 'Prefers bright indirect light', timeoutMs: 700 } },
+    expect: 'the detail screen is still fetching; its text arrives shortly',
+  },
+  {
+    name: 'secondwave',
+    want: 'recovered',
+    // The list renders its count header, then a third of its rows, then the
+    // rest. `Jade #24` is in the last wave, so a tight wait for it fails while
+    // the screen is *stable and incomplete at the same moment* — the state that
+    // has fooled settle detection and the supervisor alike.
+    walk: [{ swipe: { from: [201, 300], to: [201, 620] } }],
+    arrive: null,
+    judge: { waitFor: { value: 'Jade #24', timeoutMs: 700 } },
+    expect: 'the list arrives in waves and this row is in the last one',
+  },
+  {
+    name: 'blocked',
+    want: 'stopped',
+    walk: [
+      { tap: 'Forms, tab, 2 of 3' }, { pause: 900 }, { tap: 'Stepped form' }, { pause: 900 },
+      { tap: 'Next' }, { pause: 1200 }, { tap: 'Next' }, { pause: 1200 },
+    ],
+    // The review step, proved rather than hoped for.
+    arrive: 'Step 3 of 3',
+    judge: { waitFor: { value: 'Submitted', timeoutMs: 2500 } },
+    expect: 'Review is blocked until Species is filled in, and it is empty',
+  },
+  {
+    name: 'refused',
+    want: 'stopped',
+    walk: [
+      { tap: 'Forms, tab, 2 of 3' }, { pause: 900 }, { tap: 'One-step form' },
+      { pause: 6500 },
+      { type: { into: 'Your Name', text: 'Ada' } },
+      { tap: 'Submit' }, { pause: 1200 },
+    ],
+    // The rejection is on screen, so the submit demonstrably happened and
+    // failed — otherwise this fixture can pass by never having submitted.
+    arrive: 'The order was rejected',
+    // "Saved" was the string here and it fuzzy-matched "Could not save: …", so
+    // the judge step *succeeded* on the failure it was meant to catch and the
+    // fixture produced no rulings at all. Success and failure now share no words.
+    judge: { waitFor: { value: 'Order placed', timeoutMs: 2500 } },
+    expect: 'the first submit always fails and the second works, so waiting cannot help',
+  },
+];
+
+const before = metrics.readSupervisions(dev.udid).length;
+let runs = 0;
+let skipped = 0;
+
+for (let i = 0; i < seeds; i += 1) {
+  const seed = 1000 + i * 7;
+  for (const fx of FIXTURES) {
+    await reviveIfWedged();
+    await launchSeeded(seed);
+    const reached = await walk(fx.walk, fx.arrive);
+    if (!reached) {
+      process.stdout.write(`  seed ${seed}  ${fx.name.padEnd(9)} SKIPPED — could not reach the fixture\n`);
+      skipped += 1;
+      continue;
+    }
+    try {
+      await actions.runScript(device, {
+        steps: [{ ...fx.judge, expect: fx.expect }],
+        supervise: fx.name,
+        verify: true,
+      });
+    } catch { /* a failing step is the point */ }
+    runs += 1;
+    process.stdout.write(`  seed ${seed}  ${fx.name.padEnd(9)} judged\n`);
+  }
+}
+
+const all = metrics.readSupervisions(dev.udid);
+const fresh = all.slice(before);
+console.log(`\n${runs} judged step(s), ${skipped} skipped, ${fresh.length} ruling(s)\n`);
+
+const byFixture = new Map(FIXTURES.map((f) => [f.expect, f]));
+const score = new Map(FIXTURES.map((f) => [f.name, { n: 0, right: 0, decisions: {}, outcomes: {} }]));
+let unattributed = 0;
+for (const r of fresh) {
+  const fx = byFixture.get(r.expect);
+  if (!fx) { unattributed += 1; continue; }
+  const s = score.get(fx.name);
+  s.n += 1;
+  s.decisions[r.decision] = (s.decisions[r.decision] ?? 0) + 1;
+  s.outcomes[r.outcome] = (s.outcomes[r.outcome] ?? 0) + 1;
+  if (r.outcome === fx.want) s.right += 1;
+}
+
+console.log(`${'fixture'.padEnd(10)} ${'n'.padStart(3)} ${'right'.padStart(6)}  wanted      decisions / outcomes`);
+for (const fx of FIXTURES) {
+  const s = score.get(fx.name);
+  const pct = s.n ? `${Math.round((100 * s.right) / s.n)}%` : '—';
+  console.log(
+    `${fx.name.padEnd(10)} ${String(s.n).padStart(3)} ${pct.padStart(6)}  ${fx.want.padEnd(10)}  `
+    + `${JSON.stringify(s.decisions)} / ${JSON.stringify(s.outcomes)}`,
+  );
+}
+if (unattributed) console.log(`\n${unattributed} ruling(s) came from a step this script did not label.`);
+
+// Said before the accuracy is read, not after. The first population was 12
+// `stop` to 2 `wait`, so a majority-class guess scored 86% against the model's
+// 64% — and every number computed from it was an artifact of that skew. A
+// scoreboard that prints accuracy without printing its own balance invites
+// exactly that mistake a second time.
+{
+  const want = {};
+  for (const fx of FIXTURES) {
+    const s = score.get(fx.name);
+    want[fx.want] = (want[fx.want] ?? 0) + s.n;
+  }
+  const total = Object.values(want).reduce((a, b) => a + b, 0);
+  const biggest = Math.max(0, ...Object.values(want));
+  const baseline = total ? Math.round((100 * biggest) / total) : 0;
+  console.log(`\nbalance: ${JSON.stringify(want)} — guessing the commonest answer scores ${baseline}%.`);
+  if (baseline > 65) {
+    console.log('  SKEWED. Any accuracy above is mostly a fact about the fixture set, not the judge.');
+    console.log('  Add fixtures for the under-represented answer before comparing anything against anything.');
+  }
+}
+console.log(`\nthe log now holds ${all.length} ruling(s) — simframe supervisions --device=${dev.udid}`);

package/scripts/eval-fingerprint.mjs

@@ -87,6 +87,43 @@ const readings = [];
 /** Navigations that did not land before the reading was taken. */
 const arrivalFailures = [];
 
+/**
+ * The tokens that carry a name, as opposed to a shape.
+ *
+ * A fingerprint is deliberately geometry — role, region, size, position — and
+ * chrome labels are the only text that survives into it (`fingerprint.js`).
+ * That module's own comment states the consequence: "two list screens with
+ * identical structure differ by their title, and nothing else says so". So a
+ * reading with none of these has no identity to speak of, and two such
+ * readings of *different* screens can hash identically. Counted here because
+ * that is diagnosable and "the tour went somewhere unintended" is not.
+ */
+const namedTokens = (tokens) => tokens.filter((t) => t.includes('"'));
+
+/**
+ * Write the readings out now, rather than after the checks.
+ *
+ * The write used to sit past every `process.exit(1)`, so the only run that
+ * kept its evidence was the run with nothing to explain. A failing run exited
+ * before the file existed and `if: always()` on the upload step faithfully
+ * uploaded nothing — which is how one red integration job cost an evening of
+ * inferring from a summary line while `analyse-fingerprint.mjs`, which exists
+ * to classify exactly these divergences, had no file to read. Called as soon
+ * as the tour is done and again with the analysis, so every exit below this
+ * point still leaves the readings behind.
+ */
+const save = (extra = {}) => {
+  if (!outFile) return;
+  fs.writeFileSync(outFile, JSON.stringify({
+    label, device: dev.name, runtime: dev.runtime, rounds, at: Date.now(),
+    threshold: graph.SIMILARITY_THRESHOLD,
+    // Tokens are kept. They were stripped here once, and the first time the
+    // margin narrowed the run could not be diagnosed from its own output.
+    readings,
+    ...extra,
+  }, null, 2));
+};
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -136,12 +173,25 @@ for (let round = 1; round <= rounds; round += 1) {
       // like fingerprint drift.
       sources: id.entry?.sources ?? [],
     });
+    // Sensors and named tokens are on every line, not only inside a failure.
+    // Both were invisible until a run failed, and both are what the failure
+    // turns out to be about: two readings of one screen taken by different
+    // sensors do not share a hash by design, and a reading carrying no chrome
+    // label cannot be told from any other screen of the same shape. A summary
+    // line that hid those sent an evening after hosted-runner speed.
     process.stdout.write(
-      `  round ${round}  ${screen.name.padEnd(14)} ${String(id.hash).slice(0, 10)}  ${String((id.tokens ?? []).length).padStart(3)} tokens${id.settled ? '' : '  (never settled)'}\n`,
+      `  round ${round}  ${screen.name.padEnd(22)} ${String(id.hash).slice(0, 10)}  `
+      + `${String((id.tokens ?? []).length).padStart(3)} tokens  `
+      + `${String(namedTokens(id.tokens ?? []).length).padStart(2)} named  `
+      + `${((id.entry?.sources ?? []).join('+') || 'none').padEnd(9)}`
+      + `${id.settled ? '' : '  (never settled)'}\n`,
     );
   }
 }
 
+save();
+if (outFile) console.log(`\nwrote ${readings.length} readings to ${outFile}`);
+
 if (arrivalFailures.length) {
   console.error(`\nFAIL ${arrivalFailures.length} reading(s) were taken on the previous screen:`);
   for (const f of arrivalFailures) console.error(`       ${f}`);
@@ -178,11 +228,17 @@ function findStrays(all) {
     if (siblings.length < 2) continue;
     const bestSelf = Math.max(...siblings.map((o) => fingerprint.similarity(r.tokens, o.tokens)));
     const others = all.filter((o) => o.name !== r.name);
-    const bestOther = others.length
-      ? Math.max(...others.map((o) => fingerprint.similarity(r.tokens, o.tokens)))
-      : 0;
+    // Which screen it resembles, not merely how much. A stray that resembles
+    // one particular other screen at 1.00 is a different animal from one that
+    // resembles everything weakly, and the report could not tell them apart.
+    let match = null;
+    let bestOther = 0;
+    for (const o of others) {
+      const s = fingerprint.similarity(r.tokens, o.tokens);
+      if (s > bestOther) { bestOther = s; match = o; }
+    }
     if (bestSelf < graph.SIMILARITY_THRESHOLD && bestOther >= bestSelf) {
-      strays.push({ reading: r, bestSelf, bestOther });
+      strays.push({ reading: r, bestSelf, bestOther, match });
     }
   }
   return strays;
@@ -190,14 +246,41 @@ function findStrays(all) {
 
 const strays = findStrays(readings);
 if (strays.length) {
-  console.error(`\nFAIL ${strays.length} reading(s) were taken on a screen other than the one named:`);
-  for (const { reading, bestSelf, bestOther } of strays) {
-    console.error(`       ${reading.name} r${reading.round}: resembles its own screen ${bestSelf.toFixed(2)}, `
-      + `another screen ${bestOther.toFixed(2)} (${reading.count} tokens, sources ${reading.sources.join('+') || 'none'})`);
+  console.error(`\nFAIL ${strays.length} reading(s) do not resemble their own screen:`);
+  // Two causes wear the same symptom, and until now the report asserted the
+  // second one. A reading can be unlike its siblings because the tour went
+  // somewhere unintended — or because the fingerprint could not tell two
+  // screens apart, which is the harness's actual subject. They are separable
+  // from the data in hand: a collision is a reading that carries no chrome
+  // label while matching one particular other screen almost exactly, and a
+  // wrong turn is one whose tokens name a screen the tour did not ask for.
+  let collisions = 0;
+  for (const { reading, bestSelf, bestOther, match } of strays) {
+    const named = namedTokens(reading.tokens);
+    const matchNamed = match ? namedTokens(match.tokens) : [];
+    const collided = bestOther >= 0.99 && named.length === 0 && matchNamed.length === 0;
+    if (collided) collisions += 1;
+    console.error(`       ${reading.name} r${reading.round}: own screen ${bestSelf.toFixed(2)}, `
+      + `${match ? `${match.name} r${match.round}` : 'another screen'} ${bestOther.toFixed(2)} `
+      + `(${reading.count} tokens, ${named.length} named, sources ${reading.sources.join('+') || 'none'})`);
+    if (collided) {
+      console.error('              ^ a COLLISION, not a wrong turn: neither reading carries a chrome');
+      console.error('                label, so both are structure with no name and the fingerprint has');
+      console.error('                nothing left to tell two list screens apart.');
+    }
+    if (named.length) console.error(`              names: ${named.map((t) => t.slice(t.indexOf('"'), t.lastIndexOf('"') + 1)).join(' ')}`);
+  }
+  if (collisions) {
+    console.error(`\n${collisions} of ${strays.length} are fingerprint collisions. That is this harness's own subject,`);
+    console.error('not a tour fault: a reading whose chrome label went missing cannot establish');
+    console.error('identity, and comparing it as though it could is what produced the verdict above.');
+  } else {
+    console.error('\nThat is the tour going somewhere unintended, not the fingerprint drifting, and');
+    console.error('measuring it as either distribution poisons both ends. Fix the tour — a tap that');
+    console.error('missed, or a screen that needs longer than its pause — and re-run.');
   }
-  console.error('\nThat is the tour going somewhere unintended, not the fingerprint drifting, and');
-  console.error('measuring it as either distribution poisons both ends. Fix the tour — a tap that');
-  console.error('missed, or a screen that needs longer than its pause — and re-run.');
+  console.error(`\nEvery reading is in ${outFile ?? 'the --out file'}; `
+    + 'run `node scripts/analyse-fingerprint.mjs <that file>` to classify the divergent tokens.');
   process.exit(1);
 }
 
@@ -317,17 +400,11 @@ for (const r of readings) {
 }
 console.log(`\n${labels.size} distinct chrome label(s) entered identity: ${[...labels].sort().join(' · ') || '(none)'}`);
 
-if (outFile) {
-  fs.writeFileSync(outFile, JSON.stringify({
-    label, device: dev.name, runtime: dev.runtime, rounds, at: Date.now(),
-    threshold, same: s, mixed: m, different: d, gap, separated, thresholdInGap,
-    labels: [...labels].sort(),
-    // Tokens are kept. They were stripped here, and the first time the margin
-    // narrowed the run could not be diagnosed from its own output.
-    readings,
-  }, null, 2));
-  console.log(`\nwrote ${outFile}`);
-}
+save({
+  same: s, mixed: m, different: d, gap, separated, thresholdInGap,
+  labels: [...labels].sort(),
+});
+if (outFile) console.log(`\nwrote ${outFile}`);
 
 // The stated margin, checked rather than eyeballed. A person noticing that a
 // number moved is not a test; this is the machine that re-measures it.

package/scripts/probe-network.mjs

@@ -0,0 +1,118 @@
+// Minimal CDP client over a hand-rolled WebSocket — no dependencies, because
+// simframe has exactly one runtime dependency and this would not be it.
+//
+// Node 20 has no global WebSocket, so the upgrade and the framing are done by
+// hand. Item 80 records that the upgrade 401s without an `Origin` matching the
+// inspector's host; this sends one.
+import http from 'node:http';
+import crypto from 'node:crypto';
+
+const wsUrl = process.argv[2];
+const seconds = Number(process.argv[3] ?? 20);
+const u = new URL(wsUrl);
+
+const key = crypto.randomBytes(16).toString('base64');
+const req = http.request({
+  hostname: u.hostname,
+  port: u.port,
+  path: u.pathname + u.search,
+  headers: {
+    Connection: 'Upgrade',
+    Upgrade: 'websocket',
+    'Sec-WebSocket-Key': key,
+    'Sec-WebSocket-Version': '13',
+    Origin: `http://${u.host}`,
+  },
+});
+
+/** A client frame must be masked; the server's are not. */
+const frame = (text) => {
+  const payload = Buffer.from(text, 'utf8');
+  const mask = crypto.randomBytes(4);
+  const head = payload.length < 126
+    ? Buffer.from([0x81, 0x80 | payload.length])
+    : Buffer.concat([Buffer.from([0x81, 0xfe]), (() => { const b = Buffer.alloc(2); b.writeUInt16BE(payload.length); return b; })()]);
+  const masked = Buffer.from(payload);
+  for (let i = 0; i < masked.length; i += 1) masked[i] ^= mask[i % 4];
+  return Buffer.concat([head, mask, masked]);
+};
+
+req.on('upgrade', (res, socket) => {
+  console.log(`upgraded: ${res.statusCode} ${res.headers.upgrade ?? ''}`);
+  let buf = Buffer.alloc(0);
+  let id = 0;
+  const send = (method, params) => {
+    id += 1;
+    socket.write(frame(JSON.stringify({ id, method, params })));
+    console.log(`-> ${method}`);
+    return id;
+  };
+
+  const seen = new Map();
+  socket.on('data', (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    // Enough framing to read small unfragmented text frames, which is all CDP
+    // sends here. Deliberately not a WebSocket implementation.
+    for (;;) {
+      if (buf.length < 2) return;
+      const len0 = buf[1] & 0x7f;
+      let offset = 2;
+      let len = len0;
+      if (len0 === 126) { if (buf.length < 4) return; len = buf.readUInt16BE(2); offset = 4; }
+      else if (len0 === 127) { if (buf.length < 10) return; len = Number(buf.readBigUInt64BE(2)); offset = 10; }
+      if (buf.length < offset + len) return;
+      const text = buf.slice(offset, offset + len).toString('utf8');
+      buf = buf.slice(offset + len);
+      try {
+        const msg = JSON.parse(text);
+        if (msg.method) {
+          seen.set(msg.method, (seen.get(msg.method) ?? 0) + 1);
+          // The contents are the whole question: "settled, and these three
+          // requests fired with these statuses" is only sayable if the status
+          // and the URL are actually in here.
+          if (msg.method.startsWith('Network.')) {
+            const p = msg.params ?? {};
+            const bits = [
+              p.requestId && `id=${p.requestId}`,
+              p.request?.method && `${p.request.method} ${p.request.url}`,
+              p.response && `status=${p.response.status} ${p.response.mimeType ?? ''}`,
+              p.response?.timing && 'timing=yes',
+              p.encodedDataLength != null && `bytes=${p.encodedDataLength}`,
+              p.type && `type=${p.type}`,
+            ].filter(Boolean);
+            console.log(`   ${msg.method}: ${bits.join('  ')}`);
+          }
+        }
+        else console.log(`<- reply #${msg.id} ${msg.error ? `ERROR ${JSON.stringify(msg.error)}` : JSON.stringify(msg.result).slice(0, 120)}`);
+      } catch { /* not JSON; ignore */ }
+    }
+  });
+
+  send('Network.enable', {});
+  send('Runtime.enable', {});
+  send('Log.enable', {});
+
+  // Trigger real traffic through the app's own JS runtime, rather than through
+  // its UI. This isolates the question — does React Native's networking layer
+  // report to CDP at all — from whether my app happens to call anything, and it
+  // needs no screen, so it does not fight whatever else is driving the device.
+  setTimeout(() => {
+    send('Runtime.evaluate', {
+      expression: "fetch('https://jsonplaceholder.typicode.com/todos/1')"
+        + ".then(r => r.json()).then(j => 'FETCHED ' + JSON.stringify(j))",
+      awaitPromise: true,
+      returnByValue: true,
+    });
+  }, 1500);
+
+  setTimeout(() => {
+    console.log('\nevents received, by method:');
+    if (!seen.size) console.log('  (none)');
+    for (const [m, n] of [...seen].sort((a, b) => b[1] - a[1])) console.log(`  ${String(n).padStart(4)}x ${m}`);
+    socket.destroy();
+    process.exit(0);
+  }, seconds * 1000);
+});
+req.on('response', (res) => { console.log(`NOT upgraded: ${res.statusCode}`); process.exit(1); });
+req.on('error', (e) => { console.log('error:', e.message); process.exit(1); });
+req.end();

package/scripts/soak-capture.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// How long can this device be driven before capture wedges?
+//
+// The wedge is the thing standing between us and a ruling population: the
+// display stops rendering after a few minutes of hard driving, `simctl
+// screenshot` fails too, both of the daemon's recoveries fail, and only a
+// device restart cures it. Three times in one afternoon.
+//
+// A leak was found in our own code on 2026-09-12 — damage-callback registration
+// was not idempotent, and the recovery loop called it on every attempt, so one
+// log's 670 port re-resolves meant up to 670 live callbacks on one port, each
+// invoked per redraw. That is a real leak with a plausible path to saturating
+// the display service, and it is **not proof** that it is the cause. This is
+// how we find out: drive until it dies, and report how long that took.
+//
+//   node scripts/soak-capture.mjs --device=<udid> --minutes=25
+//
+// A number to compare against, not a pass/fail. Before the fix, the device
+// wedged roughly every 10-20 minutes of this kind of work.
+import * as actions from '../src/actions.js';
+import * as api from '../src/index.js';
+import * as store from '../src/store.js';
+
+const arg = (n, d) => {
+  const hit = process.argv.find((a) => a.startsWith(`--${n}=`));
+  return hit ? hit.slice(n.length + 3) : d;
+};
+const device = arg('device');
+const minutes = Number(arg('minutes', 20));
+const BUNDLE = 'com.example.simframetestbed';
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})   budget: ${minutes} minutes`);
+
+const started = Date.now();
+const deadline = started + minutes * 60_000;
+let laps = 0;
+let reads = 0;
+const elapsed = () => ((Date.now() - started) / 60_000).toFixed(1);
+
+// A lap is deliberately the kind of work that provokes it: launching, moving
+// between screens, and a cold read on each — not idling with a poll.
+const LAP = [
+  [{ launch: { value: BUNDLE, relaunch: true } }, { pause: 2500 }],
+  [{ tap: 'Forms, tab, 2 of 3' }, { pause: 800 }],
+  [{ tap: 'Long form' }, { pause: 900 }],
+  [{ scroll: 'down' }, { pause: 500 }],
+  [{ scroll: 'down' }, { pause: 500 }],
+  [{ tap: 'Plants, tab, 1 of 3' }, { pause: 900 }],
+  [{ tap: 'Diagnostics, tab, 3 of 3' }, { pause: 900 }],
+];
+
+while (Date.now() < deadline) {
+  for (const steps of LAP) {
+    try {
+      await actions.runScript(device, { steps, verify: false, options: { supervisor: 'none' } });
+    } catch { /* a failed step is not the subject; a dead display is */ }
+    try {
+      await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      reads += 1;
+    } catch (err) {
+      console.log(`\nWEDGED after ${elapsed()} minutes, ${laps} laps, ${reads} cold reads`);
+      console.log(`  ${String(err.message).split('\n')[0]}`);
+      const health = store.captureHealth(dev.udid);
+      if (health) console.log(`  captureHealth: ${JSON.stringify(health)}`);
+      process.exit(1);
+    }
+  }
+  laps += 1;
+  if (laps % 5 === 0) process.stdout.write(`  ${elapsed()}m  ${laps} laps  ${reads} reads  still alive\n`);
+}
+console.log(`\nSURVIVED ${minutes} minutes: ${laps} laps, ${reads} cold reads, no wedge`);