staysfixed 0.11.1 → 0.12.0

package/src/v2/browsers.js

@@ -679,10 +679,18 @@ function argsFor(ctx) {
   // Nothing pops up, and the browser itself talks to nobody. The second half
   // matters more than it looks: without it a run depends on somebody else's
   // server being awake.
+  // `--disable-extensions` is dropped when the caller is deliberately loading one. Chrome
+  // accepts both flags without a word and simply loads nothing, so an extension surface
+  // asked for through this function would have walked a browser with no extension in it and
+  // reported everything about it as unchanged — a clean answer about nothing, which is the
+  // one result this tool must never produce. Written on 2026-08-31, the day the extension
+  // surface landed, before anybody could route through here and be caught by it.
+  const loadingAnExtension = (ctx.extra ?? []).some((flag) => String(flag).startsWith('--load-extension'));
+
   args.push(
     '--no-first-run',
     '--no-default-browser-check',
-    '--disable-extensions',
+    ...(loadingAnExtension ? [] : ['--disable-extensions']),
     '--disable-background-networking',
     '--disable-component-update',
     '--disable-default-apps',

package/src/v2/check.js

@@ -56,6 +56,7 @@ import { sourceAdapter } from './adapters/source.js';
 import { httpAdapter } from './adapters/http.js';
 import { webAdapter } from './adapters/web.js';
 import { electronAdapter } from './adapters/electron.js';
+import { extensionAdapter } from './adapters/extension.js';
 
 const exec = promisify(execFile);
 
@@ -124,7 +125,7 @@ const exec = promisify(execFile);
  */
 
 /** The adapters compiled into every copy, in the order the engine trusts them. Reading the code is free, so it is first. */
-const BUILT_IN = [sourceAdapter, processAdapter, httpAdapter, webAdapter, electronAdapter];
+const BUILT_IN = [sourceAdapter, processAdapter, httpAdapter, webAdapter, electronAdapter, extensionAdapter];
 
 /**
  * The platforms that arrive as a file of their own.
@@ -158,6 +159,20 @@ const SEPARATE_ADAPTERS = [
     missing:
       'This copy has no native-Windows adapter in it. That is usually fine: a Windows product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
   },
+  {
+    surface: 'macos',
+    file: './adapters/macos.js',
+    exports: ['macosAdapter', 'adapter', 'default'],
+    missing:
+      'This copy has no native-Mac adapter in it, so nothing here can open a Swift or Objective-C app and read what is on its screen. That is usually fine: a Mac product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
+  },
+  {
+    surface: 'linux',
+    file: './adapters/linux.js',
+    exports: ['linuxAdapter', 'adapter', 'default'],
+    missing:
+      'This copy has no native-Linux adapter in it. That is usually fine: a Linux product built with Electron is driven over its own debugging port by the Electron adapter and needs nothing else.',
+  },
 ];
 
 /**
@@ -193,9 +208,12 @@ export const ADAPTER_FOR_SURFACE = {
   server: 'http',
   web: 'web',
   electron: 'electron',
+  extension: 'extension',
   android: 'android',
   ios: 'ios',
   windows: 'windows',
+  linux: 'linux',
+  macos: 'macos',
 };
 
 /**
@@ -2377,6 +2395,65 @@ async function walkOne(req, where) {
   };
 }
 
+/**
+ * Something that can walk one journey in this project, right now, without a whole check.
+ *
+ * A check is the only thing that walked a journey until 2026-08-31, and that left the
+ * recording command with a choice between running a full check to find out whether a fresh
+ * recording repeats — minutes, a store write, a verdict nobody asked for — or writing a
+ * second, simpler walker of its own, which would then be the walker that never gets fixed
+ * when the real one is. Neither is acceptable, so the walk is handed out instead: the same
+ * adapters, the same scratch-copy-per-walk rule, and the same normalisation a real check
+ * applies, so what a recording is judged on is exactly what a later check will see.
+ *
+ * The caller closes it. Everything it made lives in one throwaway folder and `close` takes
+ * that folder away.
+ *
+ * @param {{cwd?: string, root?: string, configFile?: string, config?: Record<string, any>}} [options]
+ * @returns {Promise<{root: string, config: Record<string, any>, walk: (req: WalkRequest) => Promise<Capture>, close: () => Promise<void>}>}
+ */
+export async function walkerFor(options = {}) {
+  await loadAdapters();
+  const root = projectRootFor(options);
+  const config = options.config ?? (await readConfig(options.configFile ?? findConfigFile(root)));
+  const scratch = await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-walk-'));
+  const evidenceDir = path.join(scratch, 'evidence');
+  await fsp.mkdir(evidenceDir, { recursive: true });
+  // The same rewriting a check does, and for the same reason: every walk gets its own
+  // throwaway folder, so a product that prints where it is running from would otherwise
+  // look different on every single walk — including the two walks that are meant to prove a
+  // recording repeats, which would then never repeat and no recording would ever be
+  // accepted.
+  const rules = mergeRules(DEFAULT_RULES, [
+    ...pathRules({ root, scratch }),
+    ...(await loadRules(path.join(root, '.staysfixed', 'rules.json'))),
+  ]);
+  return {
+    root,
+    config,
+    walk: async (req) => normaliseCapture(await walkOne(req, { root, scratch, evidenceDir, config }), rules),
+    close: async () => {
+      await fsp.rm(scratch, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}
+
+/**
+ * This project's settings, found the way a check finds them.
+ *
+ * Exported so that nothing else has to re-implement "walk up from here looking for a config
+ * file, and read it whether it is JSON or a module". Two readers of one settings file that
+ * disagree about where it is, is a bug that only shows up in somebody else's repository.
+ *
+ * @param {{cwd?: string, root?: string, configFile?: string}} [options]
+ * @returns {Promise<{root: string, configFile: string|null, config: Record<string, any>}>}
+ */
+export async function settingsFor(options = {}) {
+  const root = projectRootFor(options);
+  const configFile = options.configFile ?? findConfigFile(root) ?? null;
+  return { root, configFile, config: await readConfig(configFile) };
+}
+
 /**
  * @param {Journey} journey
  * @returns {Adapter|null}
@@ -2409,19 +2486,58 @@ async function gatherJourneys({ root, config, options }) {
   const gaps = [];
 
   const named =
-    options.journeys && !['code', 'config', 'suite'].includes(options.journeys) ? options.journeys : null;
-  // `recorded` is a word this tool knows and `check --help` offers it — it is simply not
-  // wired into a run yet. The MCP surface says exactly that; the command line fell through to
-  // the branch above, treated the word as a FILE PATH, and answered that a file called
-  // "recorded" was missing. The same question has to get the same answer on both.
+    options.journeys && !['code', 'config', 'suite', 'recorded'].includes(options.journeys) ? options.journeys : null;
+
+  // Sessions somebody actually performed, read back off the disk and walked like anything
+  // else. This is the one source that knows how a person really uses the product — the four
+  // screens they open every morning, in that order — and no amount of reading the source can
+  // work that out, because the source only says which doors exist, never which ones anybody
+  // opens. Until 2026-08-31 asking for it threw: the code to make a recording existed, and
+  // nothing on the check path ever read one.
+  //
+  // A run that was ASKED for recorded sessions and found none stops and says so. Carrying on
+  // with the journeys read out of the code would walk something the person did not ask for
+  // and then report "nothing that worked has broken" — a clean answer about the wrong steps,
+  // which is the one shape of reply this tool may never produce.
   if (options.journeys === 'recorded') {
-    throw new StaysFixedError(
-      'Replaying a recorded session is written and not wired into a run yet, so nothing was checked.',
-      {
-        hint: 'Leave --journeys out to use the steps each adapter reads from your source, pass `suite` to walk your own test suite, or pass the path to a journeys file.',
-      },
-    );
+    const { RECORDINGS_DIR, loadJourneyFolder, whatWillNotReplay } = await import('./journeys/record.js');
+    const dir = path.join(root, RECORDINGS_DIR);
+    const loaded = await loadJourneyFolder(dir);
+    if (loaded.journeys.length === 0) {
+      throw new StaysFixedError(
+        `You asked for recorded sessions and there are none in ${shortPath(dir)}, so nothing was checked.`,
+        {
+          hint:
+            'Make one: `staysfixed record <a-name-for-it>` opens your product, follows what you do, walks it twice to prove it repeats, and writes it there. ' +
+            `${loaded.problems.length > 0 ? `Something is already in that folder and could not be read: ${loaded.problems.join(' ')} ` : ''}` +
+            'Or leave --journeys out to use the steps each adapter reads from your source.',
+        },
+      );
+    }
+    for (const journey of loaded.journeys) {
+      // Said before it is walked, not after it fails. A recording rots quietly: the ids,
+      // ports and timestamps captured on the afternoon somebody made it go stale, and the
+      // replay then fails for a reason that has nothing to do with the product.
+      const willNotReplay = whatWillNotReplay(journey);
+      if (willNotReplay.length > 0) {
+        gaps.push({
+          what: `The recorded session "${journey.name}" may not replay.`,
+          why: willNotReplay.join(' '),
+          unlockedBy: 'Record it again with `staysfixed record`, or reach the same thing from the code or the test suite, where nothing goes stale.',
+          surface: journey.surface,
+        });
+      }
+    }
+    for (const problem of loaded.problems) {
+      gaps.push({
+        what: 'A file in the recordings folder was not walked.',
+        why: problem,
+        unlockedBy: 'Fix that file, or record the session again. A recording nothing can read is a hole, not a pass.',
+      });
+    }
+    journeys.push(...loaded.journeys);
   }
+
   if (named) journeys.push(...(await readJourneyFile(path.resolve(root, named))));
 
   // The project's own test suite, when somebody asked for it in those words and never
@@ -2501,7 +2617,11 @@ async function gatherJourneys({ root, config, options }) {
       continue;
     }
     if (!detection.applies) continue;
-    if (adapter !== sourceAdapter && named) continue;
+    // A journeys file and a recorded session both name exactly what to walk, so no adapter
+    // adds journeys of its own on top of them. The source reader is the exception: it runs
+    // nothing, it cannot break anything, and it is the only channel that sees a door nobody
+    // has ever walked through.
+    if (adapter !== sourceAdapter && (named || options.journeys === 'recorded')) continue;
     try {
       journeys.push(...(await adapter.journeys(project)));
     } catch (e) {

package/src/v2/cli.js

@@ -39,6 +39,7 @@ import { escalationBlock, escalationsFor, productFor, writeEscalations } from '.
 // module is still being evaluated.
 import { watchFlags } from '../cli/watch-flags.js';
 import { INIT_COMMANDS } from './init.js';
+import { RECORD_COMMANDS } from './journeys/record-session.js';
 import { whatWasNotChecked } from './check.js';
 
 /**
@@ -143,6 +144,7 @@ export const V2_COMMANDS = {
   // the new one actually does.
   ...INIT_COMMANDS,
   ...SHIP_COMMANDS,
+  ...RECORD_COMMANDS,
 
   check: {
     summary: 'Prove nothing that already worked has changed. This is the one you run.',

package/src/v2/coverage.js

@@ -1223,7 +1223,7 @@ function howToCover(kind, never, harvested = false) {
     case 'export':
       return harvested
         ? `The project's own tests have already been harvested and they do not reach these, so nothing existing covers them. Either they are dead code worth deleting, or they need a test that calls them — starting with "${first}".`
-        : `Write a journeys file that calls them and pass it with --journeys — starting with "${first}". (Harvesting the project's own tests would answer this for free, and that is written and not yet wired into a run.)`;
+        : `Write a journeys file that calls them and pass it with --journeys — starting with "${first}". (Or ask for a source that answers this for free: --journeys suite harvests the project's own tests.)`;
     default:
       return `Add a journey that reaches "${first}" and the ones beside it.`;
   }

package/src/v2/detect.js

@@ -60,7 +60,10 @@ export const PRODUCT_KINDS = Object.freeze({
   electron: { name: 'a desktop app built with Electron', surface: 'electron', adapter: 'electron', what: 'A desktop app. Watched by opening the built app on its own, reading its window, its menus and every private channel it registers.' },
   ios: { name: 'an iPhone or iPad app', surface: 'ios', adapter: 'ios', what: 'An Apple app. Driven on the simulator; a real device in your hand can never be compared side by side.' },
   android: { name: 'an Android app', surface: 'android', adapter: 'android', what: 'An Android app. Driven on an emulator against the stored record.' },
-  desktopNative: { name: 'a native desktop app', surface: 'windows', adapter: 'windows', what: 'A desktop app that is not Electron — Swift, WinUI, Tauri, Qt. Only readable from the operating system it runs on.' },
+  desktopNative: { name: 'a native desktop app', surface: 'windows', adapter: 'windows', what: 'A desktop app that is not Electron — Swift, WinUI, Tauri, Qt. Only readable from the operating system it runs on — Windows here; see desktopNativeLinux for Linux.' },
+  extension: { name: 'a browser extension', surface: 'extension', adapter: 'extension', what: 'Something you install in a browser. Watched by reading its manifest as a contract, opening its own pages, and comparing a page with the extension loaded against the same page without it.' },
+  macNative: { name: 'a native Mac app', surface: 'macos', adapter: 'macos', what: 'A Mac app that is not Electron — Swift or Objective-C, AppKit or SwiftUI. Readable only on a Mac, one build at a time, and one person has to allow it once under Privacy & Security.' },
+  desktopNativeLinux: { name: 'a native Linux desktop app', surface: 'linux', adapter: 'linux', what: 'A Linux desktop app that is not Electron — GTK, Qt, Tauri. Read through the accessibility bus every screen reader already uses, on a machine somebody is logged in to.' },
   container: { name: 'a containerised service', surface: 'server', adapter: 'http', what: 'A service that ships as a container. Watched the same way as any server, once there is a command that starts it.' },
   other: { name: 'a product in a language this tool cannot drive yet', surface: 'cli', adapter: null, what: 'Recognised, named, and honestly not drivable here. It is listed so a clean run is never mistaken for full coverage.' },
 });
@@ -596,7 +599,7 @@ async function productsIn(input) {
         ...(gradlew || gradle ? { buildWith: `${gradlew ? './gradlew' : 'gradle'} ${folder('app') ? ':app:assembleDebug' : 'assembleDebug'}` } : {}),
       },
       blockers: available.has('android')
-        ? ['It runs on an emulator. Whether two emulator snapshots restore identically is unproven, so a run says which mode it used.']
+        ? ['It runs on an emulator. A snapshot restore was measured on 2026-08-31 and repeats — 301 of 309 addresses agreed across five pairs, and the eight that moved were the app\'s own identity code — so a paired run is offered. It needs a kept copy of the old build\'s APK ("reference" under "android"), because a checkout of the old commit contains no build output.']
         : ['Nothing in this copy of the tool can drive an Android app yet. When it can, it will run on an emulator against the stored record.'],
     });
   }

package/src/v2/doctor.js

@@ -39,6 +39,8 @@ import { surveyBrowsers, INSTALL_COMMAND, PORT_NEVER_USE } from './browsers.js';
 import { POWERSHELL_PATHS, describeRemote } from './remote.js';
 import { deviceToMake } from './adapters/android.js';
 import { describeWindows } from './adapters/windows.js';
+import { describeLinuxDesktop } from './adapters/linux.js';
+import { describeMacos } from './adapters/macos.js';
 import { messageOf, EXIT } from '../core/errors.js';
 import { say, ok, warn, fail, blank, heading, paint, mark, shortPath, setLogLevel } from '../core/log.js';
 import { loadPlaywright } from './adapters/web-driver.js';
@@ -906,7 +908,7 @@ function findDesktopApp(cwd) {
  *
  * @param {string} root
  * @param {string|null} settingsText
- * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}>}
+ * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null, linux: FoundApp|null, macos: FoundApp|null}>}
  */
 async function phoneApps(root, settingsText) {
   // Comments taken away first, for the same reason `findDesktopApp` does it: a
@@ -923,15 +925,35 @@ async function phoneApps(root, settingsText) {
   };
 
   /**
-   * A named key whose value has to look right, so one settings word cannot be mistaken for
-   * another block's.
+   * A named key looked for INSIDE one settings block, never across the whole file.
+   *
+   * `remoteExe` means "the built program on that machine" under `windows:` and exactly the
+   * same thing under `linux:`, so a flat search finds one and reports it as the other — and
+   * doctor would tell somebody with a GTK app that they have a native Windows program.
+   * Written the day the Linux surface landed, 2026-08-31, before it could be true.
+   *
+   * @param {string} block
    * @param {string} key
-   * @param {(value: string) => boolean} looksRight
+   * @param {(value: string) => boolean} [looksRight]
    * @returns {FoundApp|null}
    */
-  const namedPath = (key, looksRight) => {
-    const found = new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(settings);
-    return found && looksRight(found[1]) ? { where: found[1], how: `your settings name it under ${key}` } : null;
+  const inBlock = (block, key, looksRight) => {
+    const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(settings);
+    if (!at) return null;
+    let depth = 0;
+    let end = at.index + at[0].length;
+    for (; end < settings.length; end += 1) {
+      if (settings[end] === '{') depth += 1;
+      else if (settings[end] === '}') {
+        if (depth === 0) break;
+        depth -= 1;
+      }
+    }
+    const inside = settings.slice(at.index + at[0].length, end);
+    const found = new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(inside);
+    if (!found) return null;
+    if (looksRight && !looksRight(found[1])) return null;
+    return { where: found[1], how: `your settings name it under ${block}.${key}` };
   };
 
   /**
@@ -974,7 +996,11 @@ async function phoneApps(root, settingsText) {
     // name one" about a project whose settings named one. Measured 2026-08-31 against a real
     // TerminalDeck.app. The value has to end in `.app` so a bare `app:` belonging to some
     // other block can never be mistaken for this one.
-    namedPath('app', (v) => v.endsWith('.app')) ??
+    // Scoped to the `ios` block, not searched across the whole file. `app` means an iPhone
+    // bundle under `ios:` and a Mac bundle under `macos:` — both end in `.app`, so a flat
+    // search finds one and announces the other. Written the day the Mac surface landed,
+    // 2026-08-31, before it could be true.
+    inBlock('ios', 'app', (v) => v.endsWith('.app')) ??
     named('xcworkspace') ??
     built(['dist', 'out', 'build', 'release'], (name) => name.endsWith('.app')) ??
     (there(path.join('ios', 'Podfile')) || readdirSafe(path.join(root, 'ios')).some((n) => n.endsWith('.xcodeproj') || n.endsWith('.xcworkspace'))
@@ -983,9 +1009,11 @@ async function phoneApps(root, settingsText) {
         ? { where: root, how: 'there is an Xcode project here, but nothing says where the built app is' }
         : null);
 
-  const windows = named('remoteExe') ?? namedPath('exe', (v) => /\.exe$/i.test(v));
+  const windows = inBlock('windows', 'remoteExe') ?? inBlock('windows', 'exe', (v) => /\.exe$/i.test(v));
+  const linux = inBlock('linux', 'remoteExe') ?? inBlock('linux', 'exe');
+  const macos = inBlock('macos', 'app', (v) => v.endsWith('.app'));
 
-  return { android, ios, windows };
+  return { android, ios, windows, linux, macos };
 }
 
 /**
@@ -1071,9 +1099,9 @@ function couldNotAsk(name, why) {
 /**
  * The platforms that arrive as an adapter of their own, and know their own requirements.
  * The built-in five are described by hand above, because they are older than this
- * mechanism and their wording is tested; these three answer for themselves.
+ * mechanism and their wording is tested; these four answer for themselves.
  */
-const ADAPTERS_THAT_ANSWER_FOR_THEMSELVES = ['android', 'ios', 'windows'];
+const ADAPTERS_THAT_ANSWER_FOR_THEMSELVES = ['android', 'ios', 'windows', 'linux', 'macos'];
 
 /**
  * Ask each separate adapter what IT is missing, in its own words.
@@ -1189,7 +1217,7 @@ async function whatThisCopyCanDrive() {
     // file that would not load, so a check on this copy is not running at all — and both
     // the command line and the MCP surface say that in their own words already.
     const why = `This copy could not be asked what it can drive: ${messageOf(e)}`;
-    for (const surface of ['android', 'ios', 'windows']) out.push({ surface, present: false, why });
+    for (const surface of ['android', 'ios', 'windows', 'linux', 'macos']) out.push({ surface, present: false, why });
   }
   return out;
 }
@@ -1550,6 +1578,7 @@ function settingsFromText(text) {
     // as a result: it could not see the machine the settings named, nor the built program,
     // so it asked for both while both were sitting in the file.
     windows: ['host', 'remoteExe', 'exe'],
+    linux: ['host', 'remoteExe', 'exe'],
   };
   for (const [block, keys] of Object.entries(wanted)) {
     const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(clean);
@@ -1679,7 +1708,7 @@ async function findReference(root) {
  * @param {import('./browsers.js').BrowserSurvey} browsers
  * @param {{where: string, how: string}|null} desktopApp
  * @param {DriverReport[]} drivers      What this copy of the tool can drive at all.
- * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}} phones
+ * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null, linux: FoundApp|null, macos: FoundApp|null}} phones
  * @param {Map<string, Need[]>} asked   What each separate adapter says IT is missing.
  * @param {{commands: number, imports: number}} [wires]
  *   What this project's own settings wire for the command-line surface. A surface with
@@ -1861,7 +1890,7 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
         : !canDrive('android')
           ? `An Android app is here (${phones.android.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('android')}`
           : androidReady
-            ? `Covered against the stored record. It installs ${phones.android.where} on a virtual device, walks it, and reads what each control on the screen is and does. Whether two emulator snapshots restore identically is still unproven, so a paired run is not offered — and the run says which mode it used.`
+            ? `Covered against the stored record. It installs ${phones.android.where} on a virtual device, walks it, and reads what each control on the screen is and does. Whether a snapshot restore repeats was measured on 2026-08-31: one build walked ten times with a restore between every walk, 301 of 309 addresses agreeing in all five pairs, and the eight that moved were the app's own freshly-made identity code — ordinary wobble, which this tool already subtracts. So a paired run is offered. It also needs a copy of the OLD build's package, because an APK is a build output that no checkout of the old commit contains: name it with {"reference": "path/to/the-old.apk"} under "android" in the settings. Without it the run falls back to the stored record and says so.`
             : androidPartly
               ? `Most of your Android app can be checked: every screen another app can reach is opened and read. What is missing is ${plainList(androidMissing)}, and without ${androidMissing.length === 1 ? 'it' : 'them'} nothing is typed, pressed or saved — so a clean result covers the screens and not what the app DOES.`
               : `An Android app is here (${phones.android.how}), and ${plainList(androidMissing)} ${androidMissing.length === 1 ? 'is' : 'are'} still missing. ${androidWants.every((n) => n.automatic) ? `${androidMissing.length === 1 ? 'It installs' : 'They all install'} without anybody clicking anything, so nobody needs to be asked.` : 'Some of it needs a person, and each one says what it is and what it unlocks.'}`,
@@ -2039,6 +2068,84 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   if (windowsHost && !windowsDriver) {
     impossible.set('windows', `${noDriver('windows')} Nothing you install on that machine changes it. Update Stays Fixed to a copy that has it.`);
   }
+
+  // ── native Mac apps ───────────────────────────────────────────────────────────────────
+  //
+  // No remote option here, unlike Windows and Linux: the Accessibility API only answers
+  // inside a signed-in graphical session on the machine itself, so a Mac app is checked on
+  // the Mac it is on or not at all. And one person has to allow it once — macOS will not let
+  // any program grant itself permission to read another app's window.
+  const macDriver = canDrive('macos');
+  const onAMacHere = process.platform === 'darwin';
+  const macNeeds = asked.get('macos') ?? [];
+  const macAllowed = onAMacHere && macDriver && !macNeeds.some((n) => /permission/i.test(String(n.what)));
+  const macUsable = phones.macos !== null && macAllowed;
+  surfaces.push({
+    id: 'macos',
+    name: 'native Mac apps',
+    status: macUsable ? 'ready' : 'unavailable',
+    summary: phones.macos === null
+      ? 'Nothing to check: this project names no native Mac app in its settings. Most Mac products are Electron, and those are covered over their debug port from any machine.'
+      : !onAMacHere
+        ? 'Cannot run here: a native Mac window can only be read from a Mac.'
+        : !macDriver
+          ? `A Mac app is named in the settings, and this copy of Stays Fixed cannot drive one. ${noDriver('macos')}`
+          // The adapter's own paragraph, not a second one written here. It knows whether this
+          // Mac has been allowed to read another app's window, and that changes the answer
+          // completely.
+          : describeMacos({ darwin: true, allowed: macAllowed }),
+    canCheck: macUsable ? [...withoutADriver, 'meaning', 'pixels'] : [],
+    cannotCheck: macUsable ? [] : CHANNELS.map((c) => c.id),
+    needs: onAMacHere && macDriver && phones.macos !== null ? macNeeds : [],
+  });
+  if (phones.macos === null) {
+    notInThisProject.add('macos');
+    impossible.set('macos', 'This project names no native Mac app in its settings, so there is nothing to open. If yours is built somewhere else, name the built .app under macos.app. Most Mac products are Electron, and those are covered over their debug port from any machine.');
+  } else if (!onAMacHere) {
+    impossible.set('macos', 'A native Mac window can only be read from a Mac. Everything else on this list is unaffected — check the Mac app from a Mac, and let this machine cover the rest.');
+  } else if (!macDriver) {
+    impossible.set('macos', `${noDriver('macos')} Nothing you install on this machine changes it. Update Stays Fixed to a copy that has it.`);
+  }
+
+  // ── native Linux desktop apps ─────────────────────────────────────────────────────────
+  //
+  // The project is asked before the machine, the same as everywhere else: a repository with
+  // no native Linux program named in it does not need a Linux desktop, and telling somebody
+  // to go and find one is work that changes nothing.
+  const linuxDriver = canDrive('linux');
+  const linuxHost = hosts.find((h) => h.reachable && h.windows !== true);
+  const linuxUsable = phones.linux !== null && linuxHost !== undefined && linuxDriver;
+  surfaces.push({
+    id: 'linux',
+    name: 'native Linux desktop apps',
+    status: linuxUsable ? 'partial' : 'unavailable',
+    summary: phones.linux === null
+      ? 'Nothing to check: this project names no native Linux program in its settings. Most Linux desktop products are Electron, and those are covered over their debug port from any machine.'
+      : !linuxDriver
+        ? `A native Linux program is named (${phones.linux.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('linux')}`
+        : !linuxHost
+          ? nobodyWasDialled
+            ? 'No machine was dialled, so whether a Linux desktop can be reached from here is unknown. Name one under `linux: { host: "..." }` in your settings and it is asked every time, or run `staysfixed doctor --machines`.'
+            : 'No Linux desktop is reachable from here. A native Linux window can only be read from the desktop it is running on.'
+          // The adapter's own paragraph, never a second one written here — it knows whether
+          // that machine has a desktop session at all, and a summary kept in this file could
+          // only guess at it.
+          : linuxHost.detail
+            ? describeLinuxDesktop(linuxHost.detail)
+            : `A Linux machine answers through "${linuxHost.name}". A native Linux app is read through the accessibility bus every screen reader already uses, and nothing has to be installed there.`,
+    canCheck: linuxUsable ? withoutADriver : [],
+    cannotCheck: linuxUsable ? ['meaning', 'pixels'] : CHANNELS.map((c) => c.id),
+    needs: linuxUsable ? (asked.get('linux') ?? []) : [],
+  });
+  if (phones.linux === null) {
+    notInThisProject.add('linux');
+    impossible.set(
+      'linux',
+      'This project has no native Linux program named in its settings, so there is nothing to open on a Linux desktop. '
+      + 'If yours is built somewhere else, name it under linux.remoteExe (already on that machine) or linux.exe (copied over each run). '
+      + 'Most Linux desktop products are Electron, and those are covered over their debug port from any machine.'
+    );
+  }
   if (!windowsHost) {
     impossible.set(
       'windows',

package/src/v2/init.js

@@ -1522,14 +1522,20 @@ export function configText(project) {
   const androidHere = android?.adapter === 'android';
   w('  // ───────────────────────────────────────────────────────────────────────');
   w('  // Android apps. Installed on an emulator of its own, walked, then removed.');
-  w('  // Compared against the stored record — whether two emulator snapshots come');
-  w('  // back byte for byte is unproven, and a run says which mode it used.');
+  w('  // Compared against the stored record, or paired if you name the old build.');
+  w('  // A snapshot restore was measured on 2026-08-31 and repeats: 301 of 309');
+  w("  // addresses agreed across five pairs, and the eight that moved were the app's");
+  w('  // own identity code, which the wobble subtraction already removes.');
   w('  // ───────────────────────────────────────────────────────────────────────');
   w(androidHere ? '  android: {' : '  // android: {');
   const andOn = androidHere ? '    ' : '  //   ';
   const apk = android?.suggest?.apk;
   w(`${andOn}// The built package. Left out, it looks in the usual build folders.`);
   w(apk ? `${andOn}apk: ${JSON.stringify(String(apk))},` : `${andOn}// apk: 'app/build/outputs/apk/debug/app-debug.apk',`);
+  w(`${andOn}// A kept copy of the OLD build's package, so a paired run has two builds to compare.`);
+  w(`${andOn}// A checkout of the old commit contains no APK — an APK is a build output — so`);
+  w(`${andOn}// without this a paired run falls back to the stored record and says so.`);
+  w(`${andOn}// reference: 'builds/0.14.0.apk',`);
   w(`${andOn}// Which emulator to use. Left out, it takes the first one that is not a Play Store image.`);
   w(`${andOn}// avd: 'Pixel_7_API_35',`);
   w(`${andOn}// Or a device already plugged in or already running.`);
@@ -1577,6 +1583,10 @@ export function configText(project) {
   w(`${iosOn}// The built app bundle for the simulator. Left out, it looks where builds land.`);
   w(iosApp ? `${iosOn}app: ${JSON.stringify(String(iosApp))},` : `${iosOn}// app: 'build/Debug-iphonesimulator/YourApp.app',`);
   w(`${iosOn}// Which simulator to use, and which system to run it on. Left out, it takes a sensible`);
+  w(`${iosOn}// A kept copy of the OLD build's bundle, so a paired run has two builds to compare.`);
+  w(`${iosOn}// A checkout of the old commit contains no .app — a bundle is a build output — so`);
+  w(`${iosOn}// without this a paired run falls back to the stored record and says so.`);
+  w(`${iosOn}// reference: 'builds/0.14.0.app',`);
   w(`${iosOn}// one and says which.`);
   w(`${iosOn}// deviceType: 'iPhone 17', runtime: 'iOS 26.4',`);
   w(`${iosOn}// Walks through the app. Left out, it opens the app and reads the first screen.`);

package/src/v2/journeys/index.js

@@ -33,7 +33,7 @@ import path from 'node:path';
 import { measureWobble } from '../observation.js';
 import { journeysFromCode } from './from-routes.js';
 import { DEFAULT_HARVEST_BUDGET_MS, harvestJourneys, testsNear } from './from-suite.js';
-import { loadJourneyFolder, whatWillNotReplay } from './record.js';
+import { RECORDINGS_DIR, loadJourneyFolder, whatWillNotReplay } from './record.js';
 
 /** @typedef {import('../types.js').Journey} Journey */
 /** @typedef {import('../types.js').JourneySource} JourneySource */
@@ -47,7 +47,7 @@ import { loadJourneyFolder, whatWillNotReplay } from './record.js';
 
 export { journeysFromCode, journeysFromDoors, irreversibility } from './from-routes.js';
 export { detectRunner, harvestJourneys, listTestFiles, testsNear, DEFAULT_HARVEST_BUDGET_MS } from './from-suite.js';
-export { startRecording, recordSession, saveJourneys, loadJourneys, loadJourneyFolder, redact } from './record.js';
+export { startRecording, recordSession, saveJourneys, loadJourneys, loadJourneyFolder, redact, RECORDINGS_DIR } from './record.js';
 
 /**
  * A journey with everything this folder knows about where it came from.
@@ -508,7 +508,7 @@ export async function gather(opts) {
 
   // ---- recorded sessions ---------------------------------------------------
   if (opts.recorded !== false) {
-    const dir = opts.recorded?.dir ?? path.join(root, '.staysfixed', 'journeys');
+    const dir = opts.recorded?.dir ?? path.join(root, RECORDINGS_DIR);
     const loaded = await loadJourneyFolder(dir);
     for (const journey of loaded.journeys) {
       const willNotReplay = whatWillNotReplay(journey);