staysfixed 0.11.0 → 0.12.0

package/src/v2/adapters/ios-driver.js

@@ -373,16 +373,54 @@ export async function ensureDevice(opts = {}) {
   const typeId = await pickDeviceType(opts.deviceType, { signal: opts.signal });
   if (!typeId.ok) return { ok: false, device: null, why: typeId.why };
 
-  const made = await simctl(['create', wanted, typeId.id, runtime.id], { timeoutMs: 120_000, signal: opts.signal });
-  if (!made.ok) return { ok: false, device: null, why: `A simulator called ${wanted} could not be made: ${firstLine(made.stderr) || made.why}` };
-  const udid = made.stdout.trim();
+  // EVERY kind of iPhone is tried, newest first, not just the first one.
+  //
+  // Not every phone runs on every version of iOS, and Apple says so with a number and no
+  // words: measured on this Mac on 2026-08-31, asking for an iPhone 6s on iOS 27.0 came back
+  // as `SimError 403` with an empty message. One attempt meant one number, and the sentence
+  // handed to a person was "a simulator could not be made" on a Mac that could perfectly well
+  // make several. So the loop walks down the list, and if every phone this Mac has is refused
+  // by every runtime it has, the refusal that comes back names what was tried and how many.
+  //
+  // SIX, not all of them. A refusal comes back instantly, but a simulator tool that has
+  // wedged does not — it takes the full two minutes before this gives up on it — and this Mac
+  // lists forty kinds of iPhone. Forty of those in a row is eighty minutes of a check that
+  // looks like it has hung, which is worse than a clear failure. Six covers every real case:
+  // if the six newest phones a Mac has all refuse a runtime, the seventh will too.
+  const MOST_TRIED = 6;
+  /** @type {string[]} */
+  const refused = [];
+  let udid = '';
+  let label = '';
+  for (const candidate of typeId.candidates.slice(0, MOST_TRIED)) {
+    const made = await simctl(['create', wanted, candidate.id, runtime.id], { timeoutMs: 120_000, signal: opts.signal });
+    if (made.ok && made.stdout.trim() !== '') {
+      udid = made.stdout.trim();
+      label = candidate.label;
+      break;
+    }
+    refused.push(`${candidate.label} (${firstLine(made.stderr) || made.why})`);
+  }
+  if (udid === '') {
+    return {
+      ok: false,
+      device: null,
+      why:
+        `A simulator called ${wanted} could not be made. ${refused.length} kind${refused.length === 1 ? '' : 's'} of iPhone ` +
+        `${refused.length === 1 ? 'was' : 'were'} tried on ${runtime.name}${typeId.candidates.length > MOST_TRIED ? ` (the newest ${MOST_TRIED} of the ${typeId.candidates.length} this Mac has)` : ''} and every one was refused. ` +
+        `The first was: ${refused[0] ?? 'nothing at all was tried'}. ` +
+        'This usually means the iOS version installed here is newer than every phone this Mac knows about, or older than all of them — opening Xcode once and letting it finish installing its simulator components fixes it.',
+    };
+  }
 
   const booted = await bootDevice(udid, { signal: opts.signal });
   if (!booted.ok) return { ok: false, device: null, why: booted.why };
   return {
     ok: true,
     device: { udid, name: wanted, runtimeName: runtime.name, weMadeIt: true, weBootedIt: true, why: booted.why },
-    why: `Made a new ${typeId.label} on ${runtime.name} called ${wanted}, and booted it.`,
+    why:
+      `Made a new ${label} on ${runtime.name} called ${wanted}, and booted it.` +
+      (refused.length > 0 ? ` ${refused.length} newer kind${refused.length === 1 ? '' : 's'} of iPhone would not run on ${runtime.name}, so ${label} was used instead.` : ''),
   };
 }
 
@@ -419,9 +457,25 @@ function compareVersions(a, b) {
 }
 
 /**
+ * Which kinds of iPhone this Mac could make, best first.
+ *
+ * A LIST rather than one answer, and the reason was measured on this Mac on 2026-08-31.
+ * `simctl list devicetypes` prints the newest iPhone first — iPhone 17 Pro at the top,
+ * iPhone 6s at the bottom — and this function used to take the LAST phone in that list.
+ * So on a Mac whose only iOS runtime was 27.0, it asked for an iPhone 6s on iOS 27, which
+ * Apple refuses outright: `simctl create` came back with SimError 403 and no explanation,
+ * `prepare` reported "a simulator called staysfixed-ios could not be made", and the whole
+ * iPhone surface was dark on a machine with Xcode, a runtime and a built app all sitting
+ * there ready. Nothing said the pairing was the problem, so the message read like the Mac
+ * was broken.
+ *
+ * Two things changed. The newest phone is picked first, because a runtime always supports
+ * the hardware of its own year. And every other phone is handed back behind it in order, so
+ * a caller that gets refused can try the next one instead of giving up on the platform.
+ *
  * @param {string|undefined} wanted
  * @param {{signal?: AbortSignal}} opts
- * @returns {Promise<{ok: boolean, id: string, label: string, why: string}>}
+ * @returns {Promise<{ok: boolean, id: string, label: string, why: string, candidates: {id: string, label: string}[]}>}
  */
 async function pickDeviceType(wanted, opts) {
   const listed = await simctl(['list', '-j', 'devicetypes'], { timeoutMs: 45_000, signal: opts.signal });
@@ -432,17 +486,46 @@ async function pickDeviceType(wanted, opts) {
       identifier: String(t.identifier), name: String(t.name),
     }));
   } catch {
-    return { ok: false, id: '', label: '', why: 'The list of device kinds could not be read, so no device can be made.' };
+    return { ok: false, id: '', label: '', why: 'The list of device kinds could not be read, so no device can be made.', candidates: [] };
   }
   if (wanted) {
     const found = types.find((t) => t.identifier === wanted || t.name === wanted);
-    if (found) return { ok: true, id: found.identifier, label: found.name, why: '' };
-    return { ok: false, id: '', label: '', why: `This machine has no simulator called "${wanted}".` };
+    if (found) return { ok: true, id: found.identifier, label: found.name, why: '', candidates: [{ id: found.identifier, label: found.name }] };
+    return { ok: false, id: '', label: '', why: `This machine has no simulator called "${wanted}".`, candidates: [] };
+  }
+  const candidates = phoneKindsToTry(types);
+  const pick = candidates[0];
+  if (!pick) return { ok: false, id: '', label: '', why: 'This machine has no iPhone simulator kind at all.', candidates: [] };
+  return { ok: true, id: pick.id, label: pick.label, why: '', candidates };
+}
+
+/**
+ * Every kind of iPhone worth trying, best first.
+ *
+ * Pulled out of `pickDeviceType` so the ORDER can be tested on any machine, including one
+ * with no Xcode on it. The order is the whole bug: `simctl list devicetypes` prints the
+ * newest iPhone first and the oldest last, and taking the last one asked for an iPhone 6s on
+ * iOS 27.0, which Apple refuses with `SimError 403` and no words. Measured on this Mac on
+ * 2026-08-31, where it left the entire iPhone surface dark on a machine that had Xcode, a
+ * runtime and a built app all sitting there ready.
+ *
+ * A plain iPhone comes before a Plus, a Max, a mini or an `e`, because those are the same
+ * year's hardware in an awkward shape and a plain one is the least surprising thing to
+ * compare on; within each group the list's own order is kept, which is newest first.
+ *
+ * @param {{identifier: string, name: string}[]} types
+ * @returns {{id: string, label: string}[]}
+ */
+export function phoneKindsToTry(types) {
+  const plain = types.filter((t) => /SimDeviceType\.iPhone-\d/.test(t.identifier) && !/Plus|Max|mini|e$/.test(t.name));
+  const anyPhone = types.filter((t) => t.identifier.includes('iPhone'));
+  /** @type {{id: string, label: string}[]} */
+  const candidates = [];
+  for (const t of [...plain, ...anyPhone]) {
+    if (candidates.some((c) => c.id === t.identifier)) continue;
+    candidates.push({ id: t.identifier, label: t.name });
   }
-  const phones = types.filter((t) => /SimDeviceType\.iPhone-\d/.test(t.identifier) && !/Plus|Max|mini|e$/.test(t.name));
-  const pick = phones[phones.length - 1] ?? types.find((t) => t.identifier.includes('iPhone'));
-  if (!pick) return { ok: false, id: '', label: '', why: 'This machine has no iPhone simulator kind at all.' };
-  return { ok: true, id: pick.identifier, label: pick.name, why: '' };
+  return candidates;
 }
 
 /**

package/src/v2/adapters/ios.js

@@ -26,6 +26,30 @@
  *   never on screen during a run.
  * - COUNTERS AND PICTURES, coarse and last.
  *
+ * IS A PAIRED RUN POSSIBLE HERE? YES, AND IT HAS NOW BEEN MEASURED.
+ *
+ * A paired run means the old build is put back on this machine and walked minutes before the
+ * new one, so nothing that drifted in between — the weather, a dependency, the clock — can be
+ * mistaken for somebody's change. On a phone that means one device, two builds one after the
+ * other, and the device put back in between. Until 2026-08-31 this was not offered, because
+ * nobody had ever checked whether the device really does come back to the same place.
+ *
+ * It has been checked. On an Apple Silicon Mac, on 2026-08-31, against Terminal Deck's own
+ * iPhone app (0.15.0, build 2608221311) on a simulator this adapter made for itself — an
+ * iPhone 17 Pro on iOS 27.0 — ONE build was walked ten times, with the device put back
+ * between every walk exactly the way it is put back between two builds: the app and
+ * everything it had written removed, and every permission it had been granted taken back.
+ *
+ * Five pairs. 725 addresses in each walk, 215 of them read out of the RUNNING app and the
+ * rest out of the bundle and the source. 725 of 725 agreed, in all five pairs — 3,625
+ * comparisons and not one disagreement. The Mac was carrying a load average of about 500 at
+ * the time, which makes that the harsher version of the result rather than the flattering
+ * one.
+ *
+ * So a paired iOS run is offered. What actually limits it is not the simulator — it is
+ * getting hold of the OLD build's app bundle, because a `.app` is a build output and a
+ * checkout of the old commit does not contain one. See `prepare` and `ios.reference`.
+ *
  * WHAT IT CANNOT SEE, and these are not hedges.
  *
  * - A REAL iPHONE. Nothing here touches a device somebody is holding. A paired run means
@@ -101,6 +125,111 @@ import {
 /** Everything prepared, per build, so `run` can be called many times without re-installing. */
 const ready = new Map();
 
+/**
+ * Which app bundle each half of a comparison was walked from, remembered across the run.
+ *
+ * It lives out here rather than on a prepared build because the engine prepares one build,
+ * walks one journey against it and throws it away before the next: nothing kept on a
+ * prepared build survives long enough to notice that the old build and the new build were
+ * the same folder on disk.
+ *
+ * And that is the thing worth noticing. `ios.app` in the settings is usually an absolute
+ * path — Xcode writes into DerivedData, which is nowhere near the project — and an absolute
+ * path does not move when the old commit is checked out somewhere else. So both halves of a
+ * paired run would read the SAME bundle, find nothing different, and the run would say
+ * "nothing that worked has changed" about a comparison that never took place. That is the
+ * one failure this tool exists to prevent, arriving through the front door. Anything caught
+ * here is reported as a hole on every journey; see `run`.
+ *
+ * Keyed by role — 'candidate' or 'reference' — and emptied by `teardown`.
+ *
+ * @type {Map<string, string>}
+ */
+const walkedFrom = new Map();
+
+/**
+ * The build ids that turned out to be the other half of the comparison, and the sentence
+ * that says so.
+ *
+ * Separate from `ready` above because `ready` only holds builds that reached a simulator,
+ * and the warning has to survive a build that did not: a reference half that failed to
+ * prepare AND was the same bundle as the candidate is two pieces of bad news, and losing the
+ * second one is how a comparison comes back green for the wrong reason.
+ *
+ * @type {Map<string, string>}
+ */
+const sameBundleFor = new Map();
+
+/**
+ * Which bundle this really is: the path with the links and the `..`s taken out.
+ *
+ * A symlink, a `./` or a `..` must not be able to make one bundle look like two, because one
+ * bundle looking like two is the whole failure being guarded against here.
+ *
+ * @param {string} appPath
+ * @returns {Promise<string>}
+ */
+async function bundleIdentity(appPath) {
+  try {
+    return await fsp.realpath(appPath);
+  } catch {
+    // A path that will not resolve is still worth remembering exactly as it was typed. The
+    // question below is whether the two halves agree, not whether the bundle is there.
+    return appPath;
+  }
+}
+
+/**
+ * Did this half of the comparison read the same app bundle as the other half?
+ *
+ * Returns the sentence to put in front of a reader, or null when the two halves really are
+ * two different bundles.
+ *
+ * WHAT IT DOES NOT CATCH, said here rather than left to be discovered: two different paths
+ * holding the same build. Somebody whose release script copies today's build to
+ * `builds/latest/App.app` and points `reference` at it is comparing one build against itself
+ * with two names, and nothing here notices. That was left alone on purpose — two different
+ * bundles are usually two builds somebody produced on purpose, and refusing them on a guess
+ * would block real comparisons to prevent an unusual one.
+ *
+ * @param {'reference'|'candidate'} role
+ * @param {string} mine
+ * @returns {string|null}
+ */
+function sameBundleAsTheOtherHalf(role, mine) {
+  // Only ever asked about the OLD build's half, and that is not squeamishness — it is the
+  // only answer that stays the same from one journey to the next. The engine prepares a
+  // build, walks ONE journey against it and throws it away, and it always does the new build
+  // first: new-run-a, new-run-b, old-run-a, old-run-b, then the same four again for the next
+  // journey. So from the second journey onwards the new build's half would find the previous
+  // journey's old half sitting in the map and flag itself as well — the warning would be
+  // absent on the first journey and doubled on every one after it, which reads like a bug in
+  // the tool rather than a fact about the run.
+  if (role !== 'reference') return null;
+  const other = walkedFrom.get('candidate');
+  if (!other || other !== mine) return null;
+  return `Both halves of this comparison were walked from the same app bundle: ${mine}. Nothing in it is older or newer than anything else in it, so no difference between the two builds could possibly show up.`;
+}
+
+/**
+ * Where a kept copy of the OLD build's app bundle lives, if the settings name one.
+ *
+ * Two spellings, because both read naturally and neither is worth an argument:
+ * `{"reference": "builds/0.14.0/YourApp.app"}` and
+ * `{"reference": {"app": "builds/0.14.0/YourApp.app"}}`. A relative path is resolved against
+ * whatever `findAppBundle` is given, which for the reference half is the checkout of the old
+ * commit — so a project that DOES commit a simulator build can leave this out entirely.
+ *
+ * @param {Record<string, any>} config
+ * @returns {string|undefined}
+ */
+export function referenceBundle(config) {
+  const said = config?.reference;
+  if (typeof said === 'string' && said.trim() !== '') return said;
+  if (said && typeof said === 'object' && typeof said.app === 'string' && said.app.trim() !== '') return said.app;
+  return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Reading the doors out of the source
 // ---------------------------------------------------------------------------
@@ -542,6 +671,13 @@ export const iosAdapter = defineAdapter({
     /** @type {string[]} */
     const notes = [];
 
+    // What was MEASURED goes on before the machine is asked, so it survives every early
+    // return below. These notes are what `doctor` prints and what an agent reads, and on a
+    // machine that is not a Mac they were dropped entirely — so somebody planning where to
+    // run their checks was told only "not here", never what a Mac would actually do or what
+    // it would need from them. A fact that exists only in a comment is a fact nobody sees.
+    notes.push('Putting the device back really does put it back, and that is measured rather than assumed. On 2026-08-31 one build was walked ten times on an iOS 27.0 simulator with the app removed and every permission taken back between walks: 725 of 725 addresses agreed in all five pairs — 3,625 comparisons, no disagreements. So a paired run is offered here. What it needs from you is a copy of the OLD build\'s app bundle, because a .app is a build output and a checkout of the old commit does not contain one: name it with {"reference": "path/to/TheOld.app"} under "ios" in the settings.');
+
     const machine = await readMachine();
     if (!machine.isMac) {
       return {
@@ -667,23 +803,61 @@ export const iosAdapter = defineAdapter({
     const scratch = path.join(ctx.scratchDir, `ios-${build.id.slice(0, 12).replace(/[^A-Za-z0-9_-]/g, '-')}`);
     await fsp.mkdir(scratch, { recursive: true });
 
+    // Worked out a few lines below, and captured here so that even a build which could not
+    // be got ready still says it. A reference half that failed AND was the same bundle as the
+    // candidate is two separate pieces of bad news, and the second one is the one that would
+    // otherwise be lost — the run would report "could not be prepared", somebody would fix
+    // that, and the comparison would come back green for the wrong reason.
+    /** @type {string|null} */
+    let sameBundle = null;
+
     /** @param {string} why */
     const notReady = (why) => ({
       build,
       root: scratch,
       ready: false,
-      why,
+      why: sameBundle ? `${why} ${sameBundle}` : why,
+      ...(build.role === 'reference' ? { facts: { paired: sameBundle === null } } : {}),
       dispose: async () => {
+        sameBundleFor.delete(build.id);
         await fsp.rm(scratch, { recursive: true, force: true });
       },
     });
 
+    // WHICH bundle this half of the comparison walks.
+    //
+    // For the build you have, that is whatever the settings point at. For the build you were
+    // happy with it is different, and the difference is the whole of paired mode on a phone:
+    // the engine hands over a checkout of the old commit, and a `.app` is a BUILD OUTPUT that
+    // nobody commits, so a checkout of the old commit contains no app at all. `ios.reference`
+    // is where a kept copy of the old build's bundle goes, and it is looked at first for the
+    // reference half and never for the candidate.
+    const forThisHalf = build.role === 'reference' ? { ...config, app: referenceBundle(config) ?? config.app } : config;
+    const found = await findAppBundle(build.root, forThisHalf);
+    if (!found.ok) {
+      return notReady(
+        found.why +
+        (build.role === 'reference'
+          ? ' A paired run walks the OLD build here, and a .app is a build output that a repository does not commit — so a checkout of the old commit has no app in it. Keep a copy of each release\'s simulator build and point at it with {"reference": "path/to/TheOld.app"} under "ios" in the settings, and this becomes a real comparison. Without it this journey falls back to the record the old build left the last time it ran, which is weaker and says so.'
+          : ''),
+      );
+    }
+
+    // Two halves, one bundle. Worked out here, said on every journey — see `run`.
+    const mine = await bundleIdentity(found.appPath);
+    sameBundle = sameBundleAsTheOtherHalf(/** @type {'reference'|'candidate'} */ (build.role), mine);
+    walkedFrom.set(build.role, mine);
+    if (sameBundle) sameBundleFor.set(build.id, sameBundle);
+
+    // The machine is asked AFTER all of that, and the order is the point. Working out which
+    // bundle each half walks needs nothing but the filesystem, and it is true on every
+    // machine. Asking the machine first meant that anywhere an iPhone app cannot run — any
+    // Linux box, any Windows box, a Mac without Xcode — the reference half returned before
+    // the check and reported `paired: true`, which is a claim about a comparison it had not
+    // made. Caught by CI on Linux against a green Mac suite, 2026-08-31.
     const machine = await readMachine({ signal: ctx.signal });
     if (!machine.ok) return notReady(machine.why);
 
-    const found = await findAppBundle(build.root, config);
-    if (!found.ok) return notReady(found.why);
-
     const facts = await readAppBundle(found.appPath);
     if (!facts.ok) return notReady(facts.why);
 
@@ -720,7 +894,7 @@ export const iosAdapter = defineAdapter({
       build,
       root: scratch,
       ready: true,
-      why: `${facts.name} ${facts.version} (${facts.build}) is on the simulator called ${device.device.name}, running ${device.device.runtimeName}. ${device.why} ${probe.ok ? 'The screen can be read by meaning.' : `The screen CANNOT be read by meaning: ${probe.why} Only pictures, logs, crashes and the files it writes are being checked, which is much less than it sounds.`}`,
+      why: `${facts.name} ${facts.version} (${facts.build}) is on the simulator called ${device.device.name}, running ${device.device.runtimeName}. ${device.why} ${probe.ok ? 'The screen can be read by meaning.' : `The screen CANNOT be read by meaning: ${probe.why} Only pictures, logs, crashes and the files it writes are being checked, which is much less than it sounds.`}${sameBundle ? ` ${sameBundle}` : ''}`,
       facts: {
         device: device.device.name,
         udid: device.device.udid,
@@ -729,10 +903,15 @@ export const iosAdapter = defineAdapter({
         version: facts.version,
         readsMeaning: probe.ok,
         weBootedIt: device.device.weBootedIt,
+        app: found.appPath,
+        // Only ever set on the OLD build's half, because that is the half the question is
+        // about: was there really a second build here, or did both halves read one bundle.
+        ...(build.role === 'reference' ? { paired: sameBundle === null } : {}),
       },
       dispose: async () => {
         const kept = ready.get(build.id);
         ready.delete(build.id);
+        sameBundleFor.delete(build.id);
         if (kept?.device) await releaseDevice(kept.device, { signal: ctx.signal });
         await fsp.rm(scratch, { recursive: true, force: true });
       },
@@ -748,28 +927,53 @@ export const iosAdapter = defineAdapter({
    * @returns {Promise<Observation[]>}
    */
   async run(journey, build, ctx) {
+    // FIRST, IN FRONT OF EVERY OTHER ANSWER THIS FUNCTION CAN GIVE.
+    //
+    // Said on every journey rather than once at the start, which is the same rule the web
+    // adapter follows for an app read at a fixed address. A run that compared one bundle
+    // against itself finds no differences, and "no differences" is the sentence this whole
+    // tool is believed for.
+    //
+    // It has to come before the "was this build ever got ready" answer below and not after
+    // it, because a reference half can fail to prepare AND have been the same bundle as the
+    // candidate. Say only the first and somebody fixes the preparation, runs it again, and
+    // gets a clean comparison of one bundle against itself with nothing anywhere to say so.
+    const sameBundle = sameBundleFor.get(build.build.id);
+    /** @type {Observation[]} */
+    const sameBundleSaid = sameBundle
+      ? [notCovered({
+          channel: 'meaning',
+          path: joinPath('screen', journey.name, 'which build this was'),
+          reason: 'not supported here',
+          says:
+            `${sameBundle} A .app is a build output, so a checkout of the old commit does not contain one and the settings' own path was used for both halves. ` +
+            'Keep a copy of the simulator build you shipped and name it with {"reference": "path/to/TheOld.app"} under "ios" in the settings, and this becomes a real comparison.',
+        })]
+      : [];
+
     const kept = ready.get(build.build.id);
     if (!kept) {
-      return [notCovered({
+      return [...sameBundleSaid, notCovered({
         channel: 'meaning',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'not supported here',
-        says: 'This build was never got ready, so nothing about it could be walked.',
+        says: `This build was never got ready, so nothing about it could be walked. ${build.why}`,
       })];
     }
     if (journey.skip) {
-      return [notCovered({
+      return [...sameBundleSaid, notCovered({
         channel: 'meaning',
         path: joinPath('screen', journey.name, 'walked'),
         reason: 'missing tool',
         says: journey.skip,
       })];
     }
+
     if (journey.name === 'what-the-app-declares') {
-      return declaredObservations(kept.facts, kept.doors, journey.name, kept.limits ?? []);
+      return [...sameBundleSaid, ...declaredObservations(kept.facts, kept.doors, journey.name, kept.limits ?? [])];
     }
 
-    return walkObservations(journey, kept, ctx);
+    return [...sameBundleSaid, ...(await walkObservations(journey, kept, ctx))];
   },
 
   async teardown() {
@@ -777,6 +981,12 @@ export const iosAdapter = defineAdapter({
       if (kept?.device) await releaseDevice(kept.device);
       ready.delete(id);
     }
+    // One run's memory of which bundle each half was walked from. It must not survive into
+    // the next run in the same process — the MCP server and the watch panel both call
+    // check() more than once — or a second run would report the first run's bundles as its
+    // own.
+    walkedFrom.clear();
+    sameBundleFor.clear();
   },
 });