staysfixed 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -8,6 +8,82 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.12.0] — 2026-08-31
+
+Five capabilities that were missing rather than broken. Each was built by a lane working on
+its own, each had to prove itself against a real product before it was believed, and three of
+the five turned up a false all-clear on the way in.
+
+### Record yourself using it once, and it is checked for ever
+
+Everything this tool checked before, it worked out by READING — routes out of the source,
+exports out of a package, screens out of a router. That finds what the code says it does. It
+never found the way somebody actually uses the thing. `staysfixed record <a-name>` now opens
+your product, follows what you do, and writes it down.
+
+- **A click that moves the page is written down as the CLICK, not the destination.** Writing
+  the destination would open that page whether or not the button works, so a broken button
+  would have come back clean. That is the whole feature failing quietly, and it is guarded.
+- **A recording is walked twice before it is accepted.** Anything that differs between the two
+  walks is not a step, it is noise, and the recording is refused rather than kept. A recording
+  that never got through its own steps even once is refused too — both walks failing
+  identically would otherwise read as perfectly steady.
+- A project that asks for recorded sessions and has none is reported as not checked, never as
+  a pass.
+
+### Phones compare two builds side by side
+
+Both phone surfaces refused a paired run because nobody knew whether an emulator or simulator
+comes back the same twice. Nobody had ever measured it. Measured now, one build walked ten
+times with a restore between every walk:
+
+- **iOS: 725 of 725 addresses agreed across five pairs.**
+- **Android: 301 of 309.** The eight that moved were the app's own freshly-made identity code
+  — ordinary wobble, which this tool already subtracts. A control run with the restore switched
+  off produced the same eight and no others, so the restore contributed exactly zero.
+
+So paired is on for both, and every sentence that repeated the old guess now carries the
+number instead. The real obstacle turned out to be somewhere else entirely: a paired phone run
+needs a kept copy of the OLD build's APK or `.app`, because a build output is in no checkout of
+the old commit. That is the new `reference` setting — and pointing it at the SAME file as the
+new build is caught and reported as a hole on every journey, rather than comparing one build
+with itself and calling it unchanged.
+
+Also fixed on the way: `simctl` lists the newest iPhone first and the adapter took the last
+one, asking for an iPhone 6s on iOS 27 — which Apple refuses with an empty message. The whole
+iPhone surface was dark on a Mac that had everything it needed.
+
+### Three new kinds of product
+
+- **Native Mac apps** (Swift or Objective-C, not Electron). Read through the Accessibility API
+  by JavaScript handed to macOS's own `osascript` — nothing is installed. Two builds of an
+  AppKit app differing by one line came back as exactly that one difference out of 75 things
+  read. **Two copies of one Mac app make one of them stop answering, and a silent app looks
+  exactly like an app with no controls** — so every read is cross-checked against the window
+  server's own list of what is on screen, and runs are one at a time.
+- **Native Linux desktop apps** (GTK or Qt). Read over ssh through the accessibility bus every
+  screen reader already uses, with nothing installed on that machine: 190 controls in 305ms,
+  the same cost as the Windows surface. A machine with nobody logged in has no accessibility
+  bus at all and is told so, rather than reported as an app with no controls.
+- **Browser extensions** (Chromium). The manifest is read as a contract — a permission that
+  appears, or a host permission widening from one named site to every site, is a change
+  somebody has to agree to, and that half needs no browser. Then the popup and options pages
+  are walked, and what a content script does to somebody else's page is measured by opening
+  that page with the extension and without it. What the background worker logs and asks the
+  network for is a named hole on every run, because both happen before anything can listen.
+
+### False all-clears found while building the above
+
+- **The browser launcher passes `--disable-extensions` unconditionally**, and Chrome accepts
+  that alongside `--load-extension` without a word and loads nothing. Anything routed through
+  it would have walked a browser with no extension in it and reported everything as unchanged.
+- **The settings lookup for a built program searched the whole file, not its own block.** `app`
+  means an iPhone bundle under `ios:` and a Mac bundle under `macos:`; `remoteExe` means the
+  same thing under `windows:` and `linux:`. Every one of them is scoped now, before the new
+  surfaces could make it true.
+- **A `reference` pointing at the same file as the new build** compares a build with itself,
+  finds nothing, and says nothing changed. Caught by real path, on every journey.
+
 ## [0.11.1] — 2026-08-31
 
 Two defects that a Mac could never have shown, both caught by CI on Linux minutes after

package/README.md

@@ -163,13 +163,17 @@ pretend otherwise.
 | The coverage ledger — every door counted, the unopened ones named, and the sentence saying so on every reply | **Works.** See [what it did not check](#what-it-did-not-check). |
 | Aiming a check at one kind of product, and refusing by name rather than checking something else | **Works.** |
 | Steps taken from your own test suite | **Works.** `--journeys suite` runs each test file twice inside the scratch copy, reports every check by name and why each failure failed, and stops after 90 seconds naming every file it did not reach. It is opt-in: running a stranger's whole suite twice on every check is not a thing to do by default. It catches what nothing else can — remove the penny-rounding from a `total()` and the product's own output does not move by one character, the discovered journeys say "nothing has changed", and the harvest names the check that turned red. |
-| Steps taken from a recorded session, or rejected at birth for not repeating twice | **Written, not wired.** The code is in `src/v2/journeys/` with tests around it, and nothing on the check path calls it yet. Ask for `--journeys recorded` and you are told so by name. |
-| Android APKs on an emulator | **The adapter is here.** It reads everything the APK declares with nothing installed and no Java, and where there is an emulator it installs one build at a time and walks it. Whether *this* machine can run one is a separate question, and `doctor` asks the adapter itself rather than keeping a second opinion — most of what it wants installs with a command; accepting Google's licence, once, needs a person. Two emulator snapshots restoring byte-identically is unproven, so Android compares against the stored record and says which mode it used. |
-| The iOS simulator | **The adapter is here.** It reads what the app bundle declares with nothing running, and where Xcode and a simulator runtime are present it installs one build at a time, boots it and reads what is on the screen. It is new. Paired running costs two `xcodebuild` passes, so it is for before a release rather than for every edit, and like Android it compares against the stored record and says which mode it used. Ask `doctor` what it is actually covering on your machine before trusting a clean run. |
+| Steps taken from a recorded session, or rejected at birth for not repeating twice | **Works.** `staysfixed record <name>` opens your product, follows what you do in it, and writes the session down; `--journeys recorded` walks it on every later check. It is the one source that knows which four screens a person actually opens every morning, which no amount of reading the source can work out. Nothing is kept until it has been walked twice against the same build: anything that differs between those two walks is noise, not a step, and the recording is refused with the reason. Passwords and tokens are taken out on the way to the file. Proved end to end on a two-page site — break the second page and the journeys read out of the code say "nothing that worked has changed", because nothing in the source names that page; the recorded session names the sentence that changed. |
+| Android APKs on an emulator | **The adapter is here.** It reads everything the APK declares with nothing installed and no Java, and where there is an emulator it installs one build at a time and walks it. Whether *this* machine can run one is a separate question, and `doctor` asks the adapter itself rather than keeping a second opinion — most of what it wants installs with a command; accepting Google's licence, once, needs a person. Two restores of one build were measured on 2026-08-31: 301 of 309 addresses agreed across five pairs, and the eight that moved were the app's own identity code, which the wobble subtraction already removes. So a paired run is offered — give it a kept copy of the old build's APK with `reference` under `android`, because a checkout of the old commit holds no build output. |
+| The iOS simulator | **The adapter is here.** It reads what the app bundle declares with nothing running, and where Xcode and a simulator runtime are present it installs one build at a time, boots it and reads what is on the screen. It is new. Paired running costs two `xcodebuild` passes, so it is for before a release rather than for every edit, and two restores of one build were measured on 2026-08-31 on an iOS 27.0 simulator and 725 of 725 addresses agreed across five pairs, so a paired run is offered — it needs a kept copy of the old build's `.app` (`reference` under `ios`), because a checkout of the old commit holds no build output. Ask `doctor` what it is actually covering on your machine before trusting a clean run. |
 | Native Windows GUI (a real Win32 app, not an Electron one) | **Works,** and it has now been driven end to end: a real Win32 window on a Windows 11 desktop reached over ssh, 10 addresses read out of the UI Automation tree, a reference cut, and the next run compared against it. Nothing was installed on that machine — the program that reads the screen is sent down the connection each run. Windows shows one desktop, so two builds can never run at once: the comparison is genuinely weaker here than anywhere else, and a run says so rather than hiding it. |
+| Browser extensions (Chromium) | **Works.** The manifest is read as a contract — a permission that appears, or a host permission that widens from one named site to every site, is reported as a change somebody has to agree to, and that half needs no browser at all. Then it loads the extension into a throwaway browser, walks its popup and options pages for what the screen means, and measures what its content scripts do to somebody else's page by opening that page with the extension and without it and comparing the two. Nothing reaches the internet. It does not read what the background worker logs or what it asks the network for — both happen in the instant the browser starts it, before anything can listen — and it says so on every run. |
+| Native Mac GUI (a Swift or Objective-C app, not an Electron one) | **Works,** and it has been driven end to end on a real Mac: two builds of an AppKit app differing by one line, 75 addresses read out of the Accessibility API each, and exactly the one changed checkbox reported. Nothing is installed — the program that reads the screen is JavaScript handed to macOS's own `osascript`. One person has to allow it once under System Settings, Privacy & Security, Accessibility; macOS will not let any program grant itself that. One build at a time: two copies of one Mac app make one of them stop answering, which looks exactly like an app with no controls, so every read is cross-checked against the window server's own list. |
+| Native Linux desktop GUI (GTK or Qt, not an Electron one) | **Works,** and it has been driven end to end: a real GTK window on an Ubuntu 24.04 desktop reached over ssh, every control read out of the accessibility bus every screen reader already uses, two runs of one build with zero unstable addresses, then a build with one checkbox ticked and one button disabled reported as exactly two differences and nothing else. Nothing was installed on that machine. A desktop shows one screen, so two builds can never run at once. A machine with nobody logged in has no accessibility bus at all, and is told so rather than reported as an app with no controls. |
 
-All eight surfaces — command-line tools, libraries, servers, websites, Electron,
-Android, iOS and native Windows — have now actually been run against a real
+All eleven surfaces — command-line tools, libraries, servers, websites, browser
+extensions, Electron, Android, iOS, native Windows, native Linux and native Mac — have now
+actually been run against a real
 product, rather than only having an adapter and tests. That sentence was not true
 before 2026-08-31, and the four that were unproven each turned out to have at
 least one defect that only running them could find.
@@ -283,15 +287,59 @@ under instrumentation → recorded real sessions → the agent exploring one nam
 gap and freezing it into a replayable file → never a person clicking through an
 app.
 
-What is wired into `staysfixed check` today is the first of those, a journeys file
-you point it at, and — when you ask for it — the project's own test suite. Each
-adapter reads your source and offers the journeys it can walk: routes, commands,
-screens, message channels. `--journeys <file>` names steps by hand. `--journeys
-suite` runs each test file twice inside the scratch copy, reports every check by
-name, and stops after 90 seconds naming every file it did not reach. Recorded
-sessions and the flake register are written and tested in `src/v2/journeys/`, and
-**nothing on the check path calls them yet**. Saying so is the point: a feature
-that exists in the repository and not in the run is not a feature you have.
+Each adapter reads your source and offers the journeys it can walk: routes,
+commands, screens, message channels. `--journeys <file>` names steps by hand.
+`--journeys suite` runs each test file twice inside the scratch copy, reports every
+check by name, and stops after 90 seconds naming every file it did not reach.
+`--journeys recorded` walks the sessions you made with `staysfixed record` — the
+one source that knows how a person actually uses the product, because every other
+one worked it out by reading, and reading only ever finds which doors exist, never
+which four somebody opens every morning. A recording is walked twice against the
+same build before it is kept, and refused with the reason if the two walks
+disagree. The flake register is written and tested and **nothing on the check path
+calls it yet**. Saying so is the point: a feature that exists in the repository and
+not in the run is not a feature you have.
+
+### Recording the session you actually perform
+
+```
+staysfixed record the-morning-round
+staysfixed check --journeys recorded
+```
+
+The first command opens your product, follows what you do in it, and writes the
+session into `.staysfixed/journeys/`. Close the window when you are done. Commit
+the file: it is the promise, not the evidence.
+
+It is the answer to the one thing reading your source can never do. The code says
+which doors exist; it never says which four you open every morning, in which
+order, with what in the boxes. Tell it once and it is checked for ever. On a
+two-page site whose second page is named nowhere in the source, breaking that page
+reports **nothing** through the journeys read out of the code — the run says
+"nothing that worked has changed" — and the recorded session names the sentence
+that changed.
+
+Nothing is kept until it repeats. The session is walked twice against the same
+build, by the same walker a later check uses, before a byte of it reaches the
+disk; if the two walks disagree about what exists, or it could not get through its
+own steps, it is refused and told why. A journey that argues with itself goes red
+on somebody else's laptop for no reason, and a check nobody trusts is worse than
+no check.
+
+Two details worth knowing. Passwords, tokens, card numbers and one-time codes are
+taken out on the way to the file, and the count of what was hidden is written into
+it. And a page move that a click caused is **not** written down as a step — a
+journey that clicked a link and then opened that address would open the second
+page whether or not the link still worked, which is exactly the false all-clear
+this tool exists to never give.
+
+Two limits, said plainly. `staysfixed record` follows you around a **web** app, in
+a browser of the tool's own; nothing yet follows your hands around a desktop or a
+phone, though `--journeys recorded` walks a recording of whatever surface its file
+names. And a recorded journey is the weakest of the sources — one path somebody
+happened to take, which goes stale when the interface moves — so anything reachable
+from your code or your test suite should come from there instead. Before a run
+walks one, it says by name what in it may not replay.
 
 ## Keeping it quiet
 
@@ -934,11 +982,14 @@ Honestly, so you know before you invest an afternoon.
   here.** No paired run is possible on a device in your hand: two builds cannot
   exist on one handset at once. Real iPhones and real Android handsets fall back
   to comparing against the stored record, and say so out loud on every run. The
-  emulator and the simulator are the honest answer, and both of them compare
-  against the stored record too — for Android because two emulator snapshots
-  restoring byte-identically is unproven, and for iOS because a paired run costs
-  two `xcodebuild` passes and belongs before a release rather than after every
-  edit. If you ship a phone app, ask `doctor` what it is actually covering before
+  emulator and the simulator are the honest answer, and both of them can be
+  paired. That was measured on 2026-08-31: iOS agreed at 725 of 725 addresses
+  across five pairs, Android at 301 of 309, and the eight Android ones that moved
+  were the app's own identity code — noise the wobble subtraction already removes.
+  What a paired phone run needs from you is a kept copy of the old build's APK or
+  `.app`, named with `reference` under `android` or `ios`, because a build output
+  is not in any checkout of the old commit. Without it the run falls back to the
+  stored record and says so on every journey. If you ship a phone app, ask `doctor` what it is actually covering before
   you trust a clean result.
 - **It is not every possible state.** "Deep" means every door the code exposes and
   every journey it was given. Nothing can enumerate every state, and any tool
@@ -955,6 +1006,13 @@ Honestly, so you know before you invest an afternoon.
   It earns the ask: take the penny-rounding out of a `total()` and the product's
   own output does not move by one character — the discovered journeys say nothing
   has changed, and the harvest names the check that turned red.
+- **A recorded session is the weakest of the sources, and it says so.** It is one
+  path somebody happened to take, and it goes stale the moment the interface it
+  describes moves — so anything reachable from the code or from your test suite
+  comes from there instead. Before a run walks one it says what in it may not
+  replay, by name. What it buys is the one thing the other sources cannot reach:
+  the way a person actually uses the product, which no amount of reading can work
+  out.
 - **No hosted service, no dashboard, no accounts, no teams, nothing paid.** It is
   a command and a folder of files in your repository.
 - **Pictures still do not travel between operating systems.** Text is drawn

package/docs/design-v2.md

@@ -17,12 +17,13 @@
 > servers, source reading, the web, Electron, Android, iOS and native Windows over ssh. The
 > MCP surface is seven tools and it is what `staysfixed mcp` serves.
 >
-> **What is written and not wired:** replaying a recorded session. The code is in
-> `src/v2/journeys/` with tests around it and nothing on the check path calls it; asking for
-> it is refused by name. Harvesting a project's own test suite was in this list and is now
-> wired — `--journeys suite`, opt-in, held to a 90-second budget, every file it did not reach
-> named. Journeys otherwise come from what each adapter reads out of your source, plus a
-> journeys file you point it at.
+> **What is written and not wired:** nothing. Replaying a recorded session was the last one
+> and it landed on 2026-08-31: `staysfixed record` opens the product, follows what a person
+> does, walks the session twice against the same build before keeping it, and `--journeys
+> recorded` walks it on every later check. Harvesting a project's own test suite was in this
+> list too and is wired — `--journeys suite`, opt-in, held to a 90-second budget, every file
+> it did not reach named. Journeys otherwise come from what each adapter reads out of your
+> source, plus a journeys file you point it at.
 >
 > **What is permanent and will not change:** nothing irreversible is ever run — it is watched
 > at the call and refused at the effect, and the refusal is reported as missing coverage;
@@ -174,7 +175,7 @@ The FlaUI probe over SSH to his office box. Built only if he ever ships a non-El
 
 ## Honest limits
 
-WHERE "EVERY PLATFORM, NO COMPROMISE" DOES NOT HOLD. Web, Electron, CLI, libraries and servers get the full paired treatment. Android and the iOS SIMULATOR get it with real work and one unproven assumption each. Real iPhones and real Android handsets do not — no paired run is possible on a device he is holding. Windows native GUI cannot run two builds at once even in principle, because UI Automation reads whatever desktop is in front. And any product whose old build can no longer be compiled — a yanked dependency, a dead toolchain — falls back to comparing against the stored record from the last time it ran. That fallback is genuinely weaker: it reintroduces every cross-day difference the paired design exists to eliminate. It must announce itself in those words on every run, not degrade quietly.
+WHERE "EVERY PLATFORM, NO COMPROMISE" DOES NOT HOLD. Web, Electron, CLI, libraries and servers get the full paired treatment. Android and the iOS SIMULATOR get it too — the assumption each was resting on was measured on 2026-08-31 and held: iOS agreed at 725 of 725 addresses across five pairs of restores, Android at 301 of 309, and the eight Android ones that moved were the app's own freshly-made identity code, which the wobble subtraction already removes. What a paired phone run needs instead is a kept copy of the OLD build's APK or .app, because a build output is not in any checkout of the old commit. Real iPhones and real Android handsets do not — no paired run is possible on a device he is holding. Windows native GUI cannot run two builds at once even in principle, because UI Automation reads whatever desktop is in front. And any product whose old build can no longer be compiled — a yanked dependency, a dead toolchain — falls back to comparing against the stored record from the last time it ran. That fallback is genuinely weaker: it reintroduces every cross-day difference the paired design exists to eliminate. It must announce itself in those words on every run, not degrade quietly.
 
 WHAT "DEEP" HONESTLY MEANS. Every door the code exposes, and every journey the existing test suite already walks. It is NOT every possible state — nothing can enumerate that, and any tool claiming otherwise is lying. The defensible claim is: it catches breaks reachable from the journeys it has, and the coverage ledger names the doors it has never opened, so the hole is visible instead of pretended away.
 

package/docs/getting-started.md

@@ -88,9 +88,11 @@ What comes back:
 finds there — routes, commands, screens, message channels — and `--journeys <file>` names
 steps by hand. `--journeys suite` adds their own test suite: each test file runs twice inside
 the scratch copy, every check is reported by name, and it stops after 90 seconds naming every
-file it did not reach. Replaying a recorded session is written in `src/v2/journeys/` and is
-**not wired into a run**: ask for `--journeys recorded` and you are told so by name. Nothing
-quietly substitutes different steps and hands you a clean answer about them.
+file it did not reach. `--journeys recorded` walks the sessions they recorded with
+`staysfixed record` — the one source that knows which screens a person actually opens, which
+reading their source cannot work out. Ask for it in a project with no recordings and the run
+stops and says so; nothing quietly substitutes different steps and hands you a clean answer
+about them.
 
 ### 3. Take the first reading
 

package/docs/how-v2-works.md

@@ -126,16 +126,39 @@ Ranked, because this is the real workload question:
 4. **The agent exploring one named gap** and freezing it into a replayable file.
 5. Never a person clicking through an app.
 
-`--journeys <source>` picks between them — and **one of those five is written and
-not wired.** A run walks (1) by default: each adapter reads your source and offers
-what it finds there. `--journeys <file>` names steps by hand, and `--journeys
-suite` adds (2), the project's own test suite — each file run twice inside the
-scratch copy, every check reported by name, held to a 90-second budget with every
-file it did not reach named. Session replay lives in `src/v2/journeys/` with tests
-around it and nothing on the check path calls it; ask for `--journeys recorded` and
-you are told that by name rather than handed a clean result about steps something
-else chose. Saying so is the point: a feature that exists in the repository and not
-in the run is not a feature you have.
+`--journeys <source>` picks between them. A run walks (1) by default: each adapter
+reads your source and offers what it finds there. `--journeys <file>` names steps
+by hand. `--journeys suite` adds (2), the project's own test suite — each file run
+twice inside the scratch copy, every check reported by name, held to a 90-second
+budget with every file it did not reach named. `--journeys recorded` adds (3), the
+sessions somebody made with `staysfixed record` and kept in `.staysfixed/journeys`.
+
+**Why (3) is worth having at all.** Everything above it was worked out by READING:
+routes out of the source, exported names out of a package, screens out of a router.
+Reading finds what the code says it does, and it is completely blind to the way a
+person actually uses the thing — the four screens they open every morning, in that
+order, with that data. A recorded session is the only channel that can learn that,
+and once learned it is checked for ever. On a two-page site whose second page is
+named nowhere in the source, breaking that page reports **nothing** through the
+journeys read out of the code and is caught immediately by the recorded one.
+
+**Nothing is recorded that has not repeated.** `staysfixed record` walks a fresh
+session twice against the same build before it writes a single byte, using the very
+same walker a later check uses, and refuses it if the two walks disagree about what
+exists or if it could not get through the steps at all. A journey that argues with
+itself would go red on somebody else's laptop for no reason, and version 1 already
+proved where that ends: a flaky check does not get fixed, it gets ignored.
+
+One trap is worth knowing about, because it is the shape of a false all-clear. When
+a person clicks a link, the browser moves. Writing both down — click the link, then
+open that address — makes a journey that opens the second page whether or not the
+link still works, so a broken button comes back clean. A page move that arrives
+right after something the person did is therefore dropped: it is the result of the
+act, and the act is the step.
+
+Asking for recorded sessions in a project that has none stops the run and says so,
+naming the folder and the command that makes one. It never falls back to the steps
+read out of the source and calls that a pass.
 
 ---
 

package/docs/mcp.md

@@ -178,10 +178,12 @@ out of your source. `"suite"` walks the project's own test suite as well — eac
 test file run twice inside the scratch copy, every check reported by name and why
 each failure failed, stopping after 90 seconds with every file it did not reach
 named. It is worth asking for when a change could break behaviour the product's own
-output would never show. You can also pass a path to a journeys file. `"recorded"`
-is written in `src/v2/journeys/` and not yet wired into a run: ask for it and you
-are told so by name, rather than given a clean result about steps something quietly
-chose instead.
+output would never show. `"recorded"` walks the sessions a person made with
+`staysfixed record` and kept in `.staysfixed/journeys` — the one source that knows
+which screens somebody actually opens, which reading the source cannot work out. Ask
+for it in a project with no recordings and the reply comes back blocked, naming the
+folder and the command that makes one, rather than giving a clean result about steps
+something quietly chose instead. You can also pass a path to a journeys file.
 
 ---
 

package/docs/settings.md

@@ -406,12 +406,15 @@ anything behind in them.
 ## `android` — an APK on an emulator
 
 Installed on an emulator of its own, walked, then removed. Compared against the
-stored record: whether two emulator snapshots come back byte for byte is unproven,
-and every run says which mode it used.
+stored record, or paired against the old build if you keep a copy of it. 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 freshly-made identity code,
+which the wobble subtraction already removes. Every run says which mode it used.
 
 | Option | What it does |
 | --- | --- |
 | `apk` | The built package. Left out, it looks in the usual build folders. |
+| `reference` | A kept copy of the OLD build's package, for a paired run. An APK is a build output, so a checkout of the old commit has none. Also accepts `{ apk: '...' }`. Left out, a paired run falls back to the stored record and says so. |
 | `avd` | Which emulator to use. Left out, it takes the first one that is **not** a Play Store image. |
 | `serial` | A device already plugged in, or an emulator already running. |
 | `journeys[]` / `screens[]` | Walks through the app: `{ name, steps: [{ tap: 'Sign in' }] }`. Left out, it opens the app and reads the first screen. |
@@ -459,9 +462,15 @@ Installed on a simulator, opened, and read — the same roles, names and states
 person hears read out to them. One build at a time. macOS only: nothing on Linux
 or Windows can run an iOS simulator.
 
+A paired run is offered: two restores of one build were measured on 2026-08-31 on
+an iOS 27.0 simulator and 725 of 725 addresses agreed across five pairs. It needs a
+kept copy of the old build's `.app`, because a build output is not in any checkout
+of the old commit.
+
 | Option | What it does |
 | --- | --- |
 | `app` | The built app bundle for the simulator. Left out, it looks where builds land. |
+| `reference` | A kept copy of the OLD build's app bundle, for a paired run. A `.app` is a build output, so a checkout of the old commit has none. Also accepts `{ app: '...' }`. Left out, a paired run falls back to the stored record and says so. |
 | `deviceType`, `runtime` | Which simulator and which system: `'iPhone 17'`, `'iOS 26.4'`. Left out it picks a sensible one and says which. |
 | `device` | An exact simulator that already exists, by name or id. |
 | `journeys[]` | Walks through the app: `{ name, steps: [{ tap: 'Sign in' }] }`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers \u2014 as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",