simframe 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator and Android emulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [

package/scripts/ci-memory.mjs

@@ -225,10 +225,28 @@ function writeFlow(name, steps) {
   return file;
 }
 
-// A closed loop: openUrl puts Safari in front, home leaves it. Both ends are
-// screens the graph can learn, and every pass starts where the last one ended.
+// A closed loop: launching an app puts it in front, home leaves it. Both ends
+// are screens the graph can learn, and every pass starts where the last one
+// ended.
+//
+// **It used to be `openUrl https://example.com`, and that was the bug.** Item
+// 142 catalogued `simctl openurl` timing out on a loaded runner as a failure
+// class, marked it "fixed — vehicle changed", and changed the vehicle in the
+// *workflow's* step only. This loop was left on it, and so was the novel action
+// below. That is the same class-versus-symptom error the `waitFor`/`assert`
+// twin recorded: the fix went where the report pointed instead of everywhere
+// the cause reached.
+//
+// It came back on 2026-09-14: passes 2 and 3 halted at step 0, the graph never
+// got the chance to predict, and the failure read as "the outcome is predicted
+// — pass 0", which names the graph for something Safari did.
+//
+// The replacement is the vehicle item 142 measured and proved for exactly this:
+// **from inside an app, pressing home always changes the screen.** Settings is
+// already installed everywhere this runs, the launch needs no network, and
+// neither end depends on a browser cold-starting on a shared machine.
 const LOOP = writeFlow('simframe-ci-loop.json', [
-  { openUrl: 'https://example.com' },
+  { launch: { value: 'com.apple.Preferences', relaunch: true } },
   { button: 'home' },
 ]);
 // Leaving whatever screen the map was read on.
@@ -537,10 +555,23 @@ if (novelRan && novelMoved) {
 // so a run in which every pass failed to dispatch says nothing about
 // prediction. It failed the build as `pass 0` while the real cause was a
 // simctl launch timing out, three checks upstream.
-const anyPassRan = passes.some((p) => Array.isArray(p.run?.results) && p.run.results.some((r) => r.ok !== false));
-if (!anyPassRan) {
+//
+// **The rule was right and the test of it was too coarse.** `anyPassRan` asks
+// whether *any* pass ran, but prediction can only be observed on a pass AFTER
+// the one that taught the edge — so pass 1 running is not enough. On
+// 2026-09-14 pass 1 ran, passes 2 and 3 halted at step 0, and this reported
+// `pass 0` as though the graph had declined to predict. Nothing had asked it
+// to. Same sentence as the novel action three checks above: untested is not
+// broken, and the guard has to test the pass the claim actually depends on.
+const dispatched = (p) => Array.isArray(p.run?.results) && p.run.results.some((r) => r.ok !== false);
+const laterPassRan = passes.slice(1).some(dispatched);
+if (!passes.some(dispatched)) {
   skip('and once the graph has seen it, the outcome is predicted',
     'no pass dispatched a step, so the graph was never given anything to learn');
+} else if (!laterPassRan) {
+  skip('and once the graph has seen it, the outcome is predicted',
+    `only the first pass dispatched a step (${passes.slice(1).map((p, i) => `pass ${i + 2}: [${p.verdicts.join(', ')}]`).join('; ')})`
+    + ' — prediction is only observable on a pass after the one that taught the edge');
 } else {
   check(passes.some((p) => p.verdicts.includes('ok')),
     'and once the graph has seen it, the outcome is predicted',

package/scripts/eval-fingerprint.mjs

@@ -88,6 +88,8 @@ const readings = [];
 const arrivalFailures = [];
 /** Readings too bare to be a screen — see the guard where this is used. */
 const sparseReadings = [];
+/** `name|round` of every reading that stayed too sparse, so the report below can name the cause. */
+const sparseAt = new Set();
 /**
  * Below this, a reading cannot distinguish its screen from any other bare one.
  *
@@ -144,6 +146,14 @@ const save = (extra = {}) => {
  * rather than hanging the job.
  */
 const STALE_READ_RETRIES = 3;
+/**
+ * How hard to try for a reading rich enough to tell its screen apart.
+ *
+ * Backed off rather than fixed, because the thing being waited for is a screen
+ * finishing its draw, and the runner that needs this is the slow one.
+ */
+const SPARSE_READ_RETRIES = 3;
+const SPARSE_READ_WAIT_MS = 1500;
 const STALE_READ_WAIT_MS = 1000;
 
 /** When the steps that were supposed to change the screen finished. */
@@ -151,6 +161,52 @@ let navigatedAt = 0;
 /** Readings that never got a frame newer than their own navigation. */
 const staleReadings = [];
 
+/**
+ * Visit every screen once before measuring, taking no readings.
+ *
+ * **The rounds are supposed to be repeat measurements of one thing.** They were
+ * not: round 1 systematically differed from rounds 2 and 3 whenever an app was
+ * cold, because an app that has just launched has not finished publishing its
+ * accessibility tree. Measured on CI — round 1 of `browser` read `e00725fce7`
+ * with **0 named** elements where rounds 2 and 3 read `9589eb2471` with **5**,
+ * while every other screen matched across all three. That is the eval measuring
+ * app cold-start, which it never set out to measure and does not report.
+ *
+ * It was invisible for a long time because something else was paying for it:
+ * the memory-layer step runs first on CI and drives the same apps for 504s,
+ * Safari included, so the eval always met a warm device. Sharding the job
+ * removed that neighbour and the dependency surfaced immediately. The defect
+ * was always here; the neighbour was hiding it.
+ *
+ * This is **not** the same as making the readings warm. Every reading is still
+ * taken with `fresh: true` against cold screen memory, which is what "cold"
+ * means in this harness — the graph must not have seen the screen before. What
+ * the warm-up removes is a variable about the *operating system* that the
+ * fingerprint has nothing to do with.
+ *
+ * Skippable with `--no-warmup`, because the comparison is the evidence: run it
+ * both ways to see whether round 1 still disagrees with its own repeats.
+ */
+async function warmUp() {
+  const started = Date.now();
+  console.log('warming: visiting each screen once, taking no readings');
+  for (const screen of tour) {
+    if (!screen.steps?.length) continue;
+    try {
+      await actions.runScript(device, { steps: screen.steps, verify: false });
+    } catch (err) {
+      // A warm-up failure is not a result. The measured rounds below will meet
+      // the same screen and fail there with the harness's own reporting, which
+      // says which screen and writes the readings out. Failing here would cost
+      // that and report a screen that was never measured.
+      console.log(`         (warm-up could not reach "${screen.name}": ${err.message})`);
+    }
+  }
+  console.log(`warming: done in ${Math.round((Date.now() - started) / 1000)}s\n`);
+}
+
+if (!process.argv.includes('--no-warmup')) await warmUp();
+
 for (let round = 1; round <= rounds; round += 1) {
   for (const screen of tour) {
     if (screen.steps?.length) {
@@ -176,7 +232,30 @@ for (let round = 1; round <= rounds; round += 1) {
         process.exit(1);
       }
     }
-    let id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    // A read can throw, and when it does the readings so far are the evidence.
+    //
+    // This file already says so — *"Everything read so far is written out
+    // first, because a failing run is the one whose evidence matters"* — and
+    // then left this call unguarded, so a runner whose OCR overran its budget
+    // produced a raw stack trace, no `--out` file, and nothing for
+    // `analyse-fingerprint.mjs` to read. Exactly the failure the `save()` above
+    // was written to prevent, one line away from it.
+    //
+    // Not retried here. The read budget is already the client's own give-up
+    // point, so a read that overran it is a statement about the machine, and
+    // the honest thing is to say which screen and how far the tour got.
+    let id;
+    try {
+      id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+    } catch (err) {
+      save({ abandonedAt: { screen: screen.name, round, error: err.message, phase: 'reading' } });
+      console.error(`\nFAIL round ${round}, "${screen.name}" could not be read: ${err.message}`);
+      console.error(`${readings.length} reading(s) taken before this were written out.`);
+      console.error('A read that overran its budget is a fact about the host, not about the');
+      console.error('fingerprint — the budget is already the client\'s own give-up point, so');
+      console.error('raising it would only move where the wait ends.');
+      process.exit(1);
+    }
     // A reading off a frame older than the navigation is not a reading either.
     //
     // Same rule as the sparseness guard below, on the other axis, and it took a
@@ -227,13 +306,36 @@ for (let round = 1; round <= rounds; round += 1) {
     // "untested is not passed" rule the memory harness learned. A screen that
     // is genuinely this bare after a second look is a real finding.
     if ((id.tokens ?? []).length < MIN_TOKENS_FOR_A_READING) {
+      // Read again, and keep the BEST reading rather than the last one.
+      //
+      // One retry was not enough and the failure it produced pointed at the
+      // wrong thing. On CI, `settings-general` read 4 tokens twice and then
+      // scored 1.00 against the *Settings root* — because the General screen's
+      // back button is labelled "Settings", so a General seen only down to its
+      // nav bar is structurally the same screen as the root. The harness
+      // reported it as a fingerprint that does not resemble its own screen. The
+      // fingerprint was fine; the look was too short. `settings-general` reads
+      // 5 tokens when it is read properly.
+      //
+      // Best-of, not last, because these reads are samples of a screen that is
+      // still drawing: a later read is usually richer but not reliably so, and
+      // throwing away a 5-token reading because the retry saw 4 would be the
+      // same bug with more steps.
       const before = (id.tokens ?? []).length;
-      await new Promise((r) => setTimeout(r, 1500));
-      id = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+      const seen = [before];
+      for (let attempt = 1; attempt <= SPARSE_READ_RETRIES; attempt += 1) {
+        await new Promise((r) => setTimeout(r, SPARSE_READ_WAIT_MS * attempt));
+        const again = await api.screenIdentity(device, { fresh: true, confirmNovel: false });
+        seen.push((again.tokens ?? []).length);
+        if ((again.tokens ?? []).length > (id.tokens ?? []).length) id = again;
+        if ((id.tokens ?? []).length >= MIN_TOKENS_FOR_A_READING) break;
+      }
       const after = (id.tokens ?? []).length;
-      console.log(`         ("${screen.name}" read ${before} token(s) — too sparse to compare; read again: ${after})`);
+      console.log(`         ("${screen.name}" read ${before} token(s) — too sparse to compare;`
+        + ` read again: ${seen.slice(1).join(', ')} — kept ${after})`);
       if (after < MIN_TOKENS_FOR_A_READING) {
-        sparseReadings.push(`${screen.name} round ${round}: ${after} token(s) after two reads`);
+        sparseReadings.push(`${screen.name} round ${round}: ${after} token(s) after ${seen.length} reads`);
+        sparseAt.add(`${screen.name}|${round}`);
       }
     }
     // Did we actually arrive? Two differently-named screens reading the same
@@ -419,6 +521,20 @@ if (strays.length) {
     const matchNamed = match ? namedTokens(match.tokens) : [];
     const collided = bestOther >= 0.99 && named.length === 0 && matchNamed.length === 0;
     if (collided) collisions += 1;
+    // The third cause, and the one that produced this report on 2026-09-15.
+    //
+    // A reading that stayed under the token floor did not fail to resemble its
+    // screen — it never saw enough of the screen to resemble anything. On CI
+    // `settings-general` read 4 tokens and scored 1.00 against the Settings
+    // root, because the General screen's back button is labelled "Settings", so
+    // a General seen only down to its nav bar IS the root structurally. The
+    // report called that a wrong turn and sent the reader to fix the tour.
+    //
+    // Not folded into `collided` above: that one means the fingerprint had
+    // nothing to work with, which is this harness's subject. This means we did
+    // not look long enough, which is the harness's own fault and a different
+    // remedy.
+    const underRead = sparseAt.has(`${reading.name}|${reading.round}`);
     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'})`);
@@ -426,6 +542,10 @@ if (strays.length) {
       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.');
+    } else if (underRead) {
+      console.error('              ^ UNDER-READ, not a wrong turn: this reading stayed below the token');
+      console.error('                floor after every retry, so it never saw enough of its screen to');
+      console.error('                resemble one. Two screens read this thinly are the same screen.');
     }
     if (named.length) console.error(`              names: ${named.map((t) => t.slice(t.indexOf('"'), t.lastIndexOf('"') + 1)).join(' ')}`);
   }
@@ -433,6 +553,10 @@ if (strays.length) {
     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 if (strays.every((x) => sparseAt.has(`${x.reading.name}|${x.reading.round}`))) {
+    console.error('\nEvery stray above was UNDER-READ, so this says nothing about the tour or the');
+    console.error('fingerprint — the harness scored a look that was too short. The retries are in');
+    console.error('SPARSE_READ_RETRIES; a runner that needs more than they allow is the finding.');
   } 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');

package/src/platform/ios.js

@@ -13,6 +13,46 @@ import * as plist from './plist.js';
 
 const run = promisify(execFile);
 
+/**
+ * How long a `simctl` verb may take before we stop waiting.
+ *
+ * **It was 20s, and that was below what a loaded runner actually needs.** Item
+ * 142 recorded `simctl launch` "taking 47-55s" on a hosted runner and filed it
+ * under a boot that had not finished; the launches were real and the budget was
+ * simply shorter than they were. The same 20s sat on `openurl`, which is the
+ * failure class that item listed four runs of, and on `terminate`. One number,
+ * three symptoms, and every one of them read as the command refusing rather
+ * than as us leaving.
+ *
+ * 90s is chosen against that measurement — comfortably past the observed 55s
+ * worst case — and not for feel. A `simctl` verb that has not returned in
+ * ninety seconds is genuinely wrong, and says so below instead of being
+ * indistinguishable from a rejection.
+ */
+const SIMCTL_TIMEOUT_MS = 90_000;
+
+/** A local file decode, which owes nothing to device latency. */
+const PLUTIL_TIMEOUT_MS = 20_000;
+
+/**
+ * What actually went wrong, including the case that has been invisible.
+ *
+ * On a timeout `execFile` kills the child, so `stderr` is EMPTY and `message`
+ * is the bare "Command failed: xcrun simctl ..." — which reads exactly like
+ * simctl rejecting the request. Three separate investigations have started from
+ * that sentence and gone looking for a broken device. The timeout has to name
+ * itself, or the next one starts in the same wrong place.
+ */
+function simctlFailure(err, what) {
+  const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
+  if (detail) return `${what}: ${detail}`;
+  if (err.killed || err.signal === 'SIGTERM') {
+    return `${what}: simctl did not return within ${Math.round(SIMCTL_TIMEOUT_MS / 1000)}s`
+      + ' (killed by simframe, not refused by simctl — the host is loaded or the device is not answering)';
+  }
+  return `${what}: ${err.message}`;
+}
+
 // `simctl list` costs ~130ms, which would otherwise dominate every warm read,
 // so the parsed list is cached for a few seconds.
 const DEVICE_CACHE_MS = 4000;
@@ -240,24 +280,33 @@ async function launchApp(udid, bundleId, { args = [], env = {}, terminateFirst =
   for (const [k, v] of Object.entries(env)) childEnv[`SIMCTL_CHILD_${k}`] = String(v);
   try {
     await run('xcrun', ['simctl', 'launch', udid, bundleId, ...args.map(String)], {
-      timeout: 20_000,
+      timeout: SIMCTL_TIMEOUT_MS,
       env: childEnv,
     });
   } catch (err) {
     // execFile's message is just "Command failed: ..." with simctl's actual
     // complaint left in stderr. A CI run failed here and said nothing about
     // why, which is the same sin as a silent fallback.
-    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
-    throw new Error(detail ? `could not launch ${bundleId}: ${detail}` : `could not launch ${bundleId}: ${err.message}`);
+    throw new Error(simctlFailure(err, `could not launch ${bundleId}`));
   }
 }
 
 async function terminateApp(udid, bundleId) {
-  await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: 20_000 });
+  try {
+    await run('xcrun', ['simctl', 'terminate', udid, bundleId], { timeout: SIMCTL_TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(simctlFailure(err, `could not terminate ${bundleId}`));
+  }
 }
 
 async function openUrl(udid, url) {
-  await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: 20_000 });
+  // The same budget and the same reporting as `launch`, because it was the same
+  // 20s and it is the failure class item 142 counted four runs of.
+  try {
+    await run('xcrun', ['simctl', 'openurl', udid, url], { timeout: SIMCTL_TIMEOUT_MS });
+  } catch (err) {
+    throw new Error(simctlFailure(err, 'could not open the url'));
+  }
 }
 
 /**
@@ -305,10 +354,9 @@ async function setPermission(udid, action, service, bundleId) {
   const args = ['simctl', 'privacy', udid, verb, service];
   if (bundleId) args.push(bundleId);
   try {
-    await run('xcrun', args, { timeout: 20_000 });
+    await run('xcrun', args, { timeout: SIMCTL_TIMEOUT_MS });
   } catch (err) {
-    const detail = (err.stderr || '').trim().split('\n').filter(Boolean).pop();
-    throw new Error(`could not ${verb} ${service}: ${detail || err.message}`);
+    throw new Error(simctlFailure(err, `could not ${verb} ${service}`));
   }
   return `${verb === 'reset' ? 'reset' : verb + 'ed'} ${service}${bundleId ? ` for ${bundleId}` : ''}`;
 }
@@ -422,8 +470,12 @@ async function appContainer(udid, bundleId) {
  * the note at the top of plist.js.
  */
 async function readPropertyList(file) {
+  // Its own budget, deliberately not the simctl one. This reads a local file
+  // and never speaks to a device, so it has none of the latency the simctl
+  // budget exists to absorb — and a plist that takes twenty seconds to decode
+  // is a problem worth hearing about promptly.
   const { stdout } = await run('plutil', ['-convert', 'xml1', '-o', '-', file], {
-    timeout: 20_000,
+    timeout: PLUTIL_TIMEOUT_MS,
     maxBuffer: 64 * 1024 * 1024,
   });
   return plist.parse(stdout);