staysfixed 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,193 @@ All notable changes to this project are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version
 numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] — 2026-08-30
+
+The release where the front door was found to be locked.
+
+Everything written about this tool over MCP was true of code that no client could
+reach: `staysfixed mcp` served version 1's picture tools, and `staysfixed init`
+wrote version 1's picture settings. The README, `docs/mcp.md`,
+`docs/getting-started.md` and the tool's own `capabilities` reply all described
+the difference engine. An agent that followed this project's own wiring block got
+a tool set none of the documentation mentions, and never reached the engine at
+all. Nothing was broken. Nothing was reachable either, which is worse, because it
+looks like it works.
+
+That is fixed, and so is the second half of the same mistake: `doctor` was
+confidently wrong about this machine, in three different ways, all of them
+invisible.
+
+### Changed — the front door
+
+- **`staysfixed mcp` now serves the difference engine.** Seven tools:
+  `staysfixed_capabilities`, `_intent`, `_check`, `_explain`, `_prove`, `_waive`,
+  `_coverage`. There is still no door marked approve.
+- **`staysfixed mcp --v1` serves version 1's picture tools, unchanged.** Nobody who
+  wired those up is stranded, and a test holds them there.
+- **`staysfixed init` now reads your project properly.** It works out what the
+  repository actually makes, writes settings with an explanation beside every
+  option, never overwrites a file you already have, and answers with
+  `plan.project`, `plan.readiness`, `plan.needs.agent`, `plan.needs.person`,
+  `plan.needs.impossible`, `plan.journeys`, `plan.covers.short` and `plan.wiring`
+  under `--json`. `docs/getting-started.md` was written entirely around those
+  fields against a command that did not produce any of them.
+- **Settings for a product with no screen are no longer a puzzle.** `status`,
+  `walk`, `approve`, `mark`, `trace` and `check --pictures` all work by opening
+  something and photographing it, and a command-line tool has nothing to open —
+  which is the correct shape for its settings, not a mistake. They used to answer
+  "Stays Fixed does not know what to open" and tell you to add a web address you do
+  not have. They now say which half of the tool needs a screen, and name the half
+  that covers you without one.
+
+### Added — the MCP surface an agent reads before it calls anything
+
+- **Every tool carries a short title and the protocol's own flags for what it does
+  to your machine.** `staysfixed_capabilities`, `staysfixed_explain` and
+  `staysfixed_coverage` are read-only and idempotent; `staysfixed_check` and
+  `staysfixed_prove` open your product, so they are neither; and none of the seven
+  claims to reach the outside world, because none of them does. A client can now
+  tell a question from an action without reading any documentation.
+- **`journeys: "suite"` and `journeys: "recorded"` are refused by name.** Both are
+  written and tested in `src/v2/journeys/`, and nothing on the check path calls
+  them, so both used to reach the engine as the name of a file and come back as
+  "there is no journeys file at .../suite" — an error that sends an agent looking
+  for a file it never asked for.
+
+### Fixed — `doctor` was wrong about this machine
+
+All three were found by running it on a real Mac and checking every line it
+printed, which is the only way this kind of mistake is ever found.
+
+- **It asked `command -v powershell.exe` over ssh to decide whether Windows sits
+  behind a machine.** That question answers "no" on a machine with a real Windows
+  desktop right there: the path is put on `PATH` by an interactive login shell, and
+  ssh does not run one. The one true Windows runner in this machine's ssh config
+  was reported as not Windows. It asks the filesystem now, for the three places
+  PowerShell actually lives, using the same list the code that later drives it
+  uses — one list, not two.
+- **It read a refusal as an answer.** `ssh github-imza 'echo staysfixed-reachable'`
+  is refused by github.com with `Invalid command: echo staysfixed-reachable`, on
+  stderr, quoting the command back. A probe that looked for its own word anywhere
+  in either stream found it inside the refusal, so three git hosts were listed as
+  machines this tool could run checks on — and, by the same bug, as Windows
+  desktops. It reads standard output only now, and matches the whole line.
+- **It named the first eight machines in an ssh config and dropped the rest without
+  a word.** It dials sixteen, and anything past that is named as not dialled rather
+  than left out. Undercount and say so; never quietly stop short.
+- **It reported Docker as present because the command was on the path**, on a
+  machine where Docker Desktop was shut and nothing it promises would have worked.
+  It asks the engine for its version now.
+- No probe in `doctor` uses a shell variable or a loop any more. One machine in
+  this config reaches Windows through an OpenSSH server that hands the command down
+  through a second shell, and every `$p` is expanded to nothing before the shell
+  meant to read it sees it — `for p in "A"; do echo "$p"; done` prints an empty
+  line there. Literal arguments only.
+
+### Fixed — what an agent actually reads
+
+- **`staysfixed_explain` printed `(SEALED: [object Object])`** on the one reply an
+  agent reads when it is trying to understand a difference it may not waive.
+- **The same sentence arrived twice in one check reply** — "not everything was
+  checked", once under the headline and again inside the summary — and the values
+  of a one-address finding were printed twice in `explain`. Both are said once now.
+- **`staysfixed_coverage` printed the same line three times.** Several of the
+  coverage caveats share one headline and differ entirely in their reason, so a
+  list of headlines was one sentence repeated and none of the three reasons. The
+  reason is printed with each.
+- **"2 journeys were walked" no longer sits one line above "2 of the 2 ways into
+  this product have never been walked through."** Both numbers were right and the
+  two sentences contradicted each other on screen: a journey is one route through
+  the product, a door is one way into it, and they now have two different words.
+- **The tool no longer advises you to do something it cannot do.** Three places
+  told you to harvest your own test suite as journeys. That is written and not
+  wired, so all three now name what does work today.
+
+### Changed — what a fresh install pulls
+
+- **`playwright` is out of `dependencies`.** Nothing in `src/` imports it — browsers
+  are driven over the debugging protocol by code in this repository — and having it
+  there made a fresh `npm install staysfixed` pull about 18MB against a README
+  promising two packages under a megabyte. It stays a `devDependency`, and it is
+  still what `doctor` tells you to install in YOUR project when you want a browser
+  of your own.
+- **`docs/` ships with the package**, so an agent that installed this from npm can
+  read `docs/getting-started.md` without a network.
+
+### Changed — everything else in this batch
+
+- **A check gives your screen back.** An app the tool opens comes to the front once,
+  because that first appearance is how you see what is happening; from the moment
+  you pick something else, anything the tool launched loses the argument
+  permanently. The window it opens is placed beside the app rather than over it,
+  and a window that is going to be left up is waited for while one that is going
+  away is not.
+- **The store writes whole lines or says plainly that it did not.** A full disk is
+  the one storage failure that happens to real people mid-run, and it now reads as
+  a full disk rather than as a corrupt record.
+- **Ranking says which of two answers it has.** When distance from the edit cannot
+  be worked out, the finding is still reported and still counted, and the reply
+  says that its position is a guess rather than letting the order imply a
+  confidence nobody has.
+- **The self-check corpus grew again**, including a case where the store itself
+  cannot be written to — a machine-shaped failure that has to come back as "no
+  answer" rather than as a clean run.
+- **The scratch checkout a causal proof makes is put away, and says so plainly when
+  it will not go.** A file that vanished between git listing it and the copy
+  reaching it is not a failure; a directory that will not delete is, and the two
+  used to share one empty catch.
+
+## [0.6.2] — 2026-08-30
+
+Something to watch it with, and the first proof on a real product that somebody
+else built.
+
+### Added
+
+- **A live panel showing what the tool now is.** Version 1's panel showed screens
+  and pictures, because that is what version 1 did. This one shows a product being
+  proven unchanged: which surface each journey walks, which build it is being
+  measured against and how that build was chosen, addresses ticking up as they are
+  watched, how much wobble was measured and subtracted, the findings that survived,
+  what was **not** checked, and the one or two things only a person may decide. The
+  wobble figure is given room on purpose — it is the number that explains why the
+  tool is quiet.
+- **A focus guard, so watching it work never costs you your screen.** An app the
+  tool opens is allowed to come to the front once, because that first appearance is
+  how you see what is happening. From the moment you pick something else, anything
+  the tool launched loses the argument permanently. There is no flag for it and
+  nothing to configure: an Electron app calls `focus()` from its own main process, a
+  simulator activates when it boots, a browser activates when a window opens, and
+  none of that goes through us — so the only thing that works is watching who is in
+  front and handing the screen straight back. It learns which application is yours
+  by watching what you choose, never by being told, and it says nothing at all
+  unless it actually had to act. Measured on a real desktop app: five grabs over
+  five seconds, five handed straight back.
+
+### Fixed
+
+- Three rendering defects, each of which would have told somebody something untrue:
+  a verdict trimmed twice, so a run with four findings — two of them sealed —
+  announced *"Everything that worked still works"*; a build that lost its name on a
+  second trim and became "an unnamed build"; and a `\b` inside a template literal
+  eaten before the regular expression saw it, so permanent coverage gaps were
+  painted as though a person could act on them.
+- **A check that finished before its window opened waited out a twenty-second
+  timeout.** The check never waited on the panel, but stopping did: a 2.2 second
+  check took 20.7 seconds of wall time. Opening is cancellable now and a window that
+  arrives late closes itself. A 100ms check ends in 277ms.
+
+### Proven
+
+- On a real product that somebody else built: a reference cut at **15,147
+  addresses** across 17 journeys, two agent-shaped breaks caught in 12.6 seconds
+  with the break far from the edit correctly outranking the one inside it, and
+  silence restored when both were undone. Its iPhone app built and driven in a
+  simulator of the tool's own; its Android app built and driven on a throwaway
+  emulator.
+- With the panel open throughout: same verdict, same 1,776 addresses, 110 events
+  pushed, 104 delivered, none dropped. Closing it mid-run changes nothing.
+
 ## [0.6.1] — 2026-08-30
 
 Documentation only, and it is a correction rather than a polish. The README

package/README.md

@@ -138,8 +138,10 @@ pretend otherwise.
 
 | | State |
 | --- | --- |
-| Picture checks, guards, walk, markers, flake register, MCP server | **Shipped.** Published as `staysfixed` 0.3.x and in use. |
-| `doctor` describing this machine in plain English and as JSON | **Shipped.** |
+| Picture checks, guards, walk, markers, flake register | **Shipped.** Published as `staysfixed` 0.3.x and in use. Reached from `staysfixed check --pictures` and `--guards`, and over MCP with `staysfixed mcp --v1`. |
+| The MCP server an agent wires up — seven tools, no door marked approve | **Works,** and it is what `staysfixed mcp` serves. It served version 1's picture tools until 0.7.0, which meant every word written about the engine over MCP was true of code no client could reach. |
+| `staysfixed init` reading the repository and writing settings you can read | **Works,** and it is what `staysfixed init` runs. Also wired up in 0.7.0, for the same reason. |
+| `doctor` describing this machine in plain English and as JSON | **Shipped.** Three of its probes were wrong about the machine it was run on until 0.7.0 — see [the silences](#the-silences-that-were-found-and-closed). |
 | The difference engine — the address space, normalisation, wobble subtraction, clustering, ranking, causal proof, the store, the MCP tools, the self-check corpus | **Works.** |
 | Command-line tools, libraries and HTTP servers | **Works.** |
 | Reading the contract straight out of your source — routes, exports, message channels — without running anything | **Works.** 5,785 doors read out of one desktop app in 1.4 seconds. |
@@ -155,8 +157,14 @@ pretend otherwise.
 
 `staysfixed check` is the front door for both. Version 1's flags still mean
 exactly what they meant yesterday — `--pictures`, `--guards`, `--watch` and
-`--only` reach the same code they always did. Nobody who installed this last week
-has to change anything.
+`--only` reach the same code they always did, on the settings you already have,
+and `staysfixed mcp --v1` still serves the picture tools. Nobody who installed
+this last week has to change anything.
+
+The one thing that did change: `staysfixed init` now writes settings for the
+difference engine. On a product with no screen those settings have no `app` block
+in them, and the picture commands say so plainly rather than telling you to invent
+a web address. Add an `app` block yourself if you want picture checks too.
 
 ## How it proves nothing changed
 
@@ -284,7 +292,7 @@ What this run did not check
 
   391 of the 452 ways into this product have never been walked through.
       A break behind any of them is invisible to this tool. Point a journey at
-      them, or run the project's own test suite as journeys.
+      them - name the steps in a journeys file and pass it with --journeys.
 ```
 
 A **door** is any way into your product the source declares: an HTTP route, an
@@ -332,11 +340,13 @@ ACTUALLY COMPARED`**, it is not a pass, and it exits non-zero.
 
 ### The silences that were found and closed
 
-Every one of these produced a clean-looking run while something was invisible.
-They are listed because a tool like this earns trust by naming the ways it has
-been wrong, not by claiming it never was. All five were found on 2026-08-29 and
-2026-08-30 by reading the whole engine looking for the same shape as the first
-one, and each has a case in the corpus or a test holding it shut.
+Every one of these left something invisible while the answer looked complete —
+most of them a clean-looking run, and the last four an honest-looking description
+of a machine. They are listed because a tool like this earns trust by naming the
+ways it has been wrong, not by claiming it never was. All of them were found on
+2026-08-29 and 2026-08-30 by reading the whole thing looking for the same shape
+as the first one, and each has a case in the corpus, a test, or a probe rewritten
+to ask the question a different way.
 
 | It used to | Now |
 | --- | --- |
@@ -350,6 +360,10 @@ one, and each has a case in the corpus or a test holding it shut.
 | Subtract the new build's own wobble even when the wobble had swallowed the comparison — a second run that fell over makes almost every address unsteady, everything is dropped before it is compared, and the run ends "nothing that already worked has changed" | A build that disagrees with itself about most of its own addresses gets **no verdict**: the run says NO ANSWER FROM THIS RUN, in those words, and is not a pass |
 | Keep the **first** of two facts written at one address and ignore the second, so a door that broke behind a duplicated address could never be compared with anything. The detector for this was written on day one and never called | Every walk is checked for it, and each clash is named in the coverage: which address, and what the ignored answer was |
 | Skip a folder it could not open **while looking for routes**, and every route behind it — the same bug as the one above, in a second place, still silent | Names the folder, and the routes behind it are reported as unread rather than as absent |
+| Serve version **1**'s picture tools when an agent wired up `npx staysfixed mcp` exactly as this page says to. Everything written about the difference engine over MCP was true of code no client could reach | `staysfixed mcp` serves the seven tools above. Version 1's are behind `--v1` |
+| Ask a machine `command -v powershell.exe` over ssh to find out whether Windows sits behind it — a question that answers "no" on a machine with Windows right there, because that path is added by an interactive login shell and ssh does not run one. It also read a **refusal** as an answer, so `github.com` was listed as a machine to run checks on, and as a Windows desktop | Asks the filesystem for the three places PowerShell actually lives, using the one list the code that later drives it uses. Reads standard output only, and matches the whole line, so a host that quotes your command back cannot answer for itself |
+| Name only the first eight machines in an ssh config and drop the rest without a word | Dials sixteen, and anything past that is named as not dialled rather than left out |
+| Report Docker as present because the command is on the path, on a Mac where Docker Desktop is shut and nothing it promises would work | Asks the engine for its version, and says "installed but not answering" when that is the truth |
 
 ---
 
@@ -522,6 +536,15 @@ opts in, so the agent never sees a door to push on. An agent that could bless it
 own results would edit the code, notice something moved, approve it, and report
 success, and your safety net would have become a rubber stamp.
 
+Every tool in that list also carries a short title and the protocol's own flags
+for what it does to your machine, so a client can tell a question from an action
+without reading this page: `staysfixed_capabilities`, `staysfixed_explain` and
+`staysfixed_coverage` are marked read-only, and none of the seven is marked as
+reaching the outside world, because none of them does.
+
+`staysfixed mcp` serves the tools above. The version 1 picture tools are still
+there behind `staysfixed mcp --v1` for anybody who wired those up, unchanged.
+
 Full wiring for every client: [docs/mcp.md](docs/mcp.md).
 
 ### Nothing here should need a human to read documentation
@@ -611,15 +634,35 @@ replays recorded traffic and never reaches the real world.
 
 ## Settings
 
-Everything is optional except `app`. A five-line file works, and
-`staysfixed init` writes one you can read. A `staysfixed.config.json` works too,
-with a declarative `steps` form and no functions — so a Rust, Python or Go
-project can use the tool without anybody writing JavaScript.
-
-Two fully commented examples are in [`examples/`](examples/):
+**You should not have to write these.** `staysfixed init` reads the repository —
+`package.json`, the lockfile, the framework config, the folder shapes, the built
+artifacts, an `.app`, an `.xcodeproj`, a `gradlew`, a Dockerfile, the test runner,
+and every route, exported name and message channel written in the source — works
+out what the repository actually makes, and writes settings with an explanation
+beside every option. It never overwrites a file you already have. `staysfixed init
+--json` is the same answer as one object, which is what an agent should read.
+
+A repository usually makes more than one thing, and a list of four is normal: one
+repository producing a desktop app, an iPhone app, an Android app and a website is
+the case this was built against.
+
+What it writes names the product and one block per kind of thing it found —
+`process` for commands, `http` for a server, `web` for a website, `electron`,
+`android`, `ios`, `windows`. **A product with no screen has no `app` block, and
+that is correct**: the picture commands (`status`, `walk`, `approve`, `mark`,
+`trace`, `check --pictures`) work by opening something and photographing it, so
+they need an `app` and say so plainly if there is not one. `staysfixed check`
+needs no `app` at all.
+
+A `staysfixed.config.json` works too, with a declarative `steps` form and no
+functions — so a Rust, Python or Go project can use the tool without anybody
+writing JavaScript.
+
+Three fully commented examples are in [`examples/`](examples/):
 [a web app](examples/staysfixed.config.web.js),
 [an Electron app](examples/staysfixed.config.electron.js), and
-[a guard](examples/guards/the-sidebar-still-collapses.js).
+[a guard](examples/guards/the-sidebar-still-collapses.js). All three are written
+for the picture check, which is the half that needs an `app`.
 
 The full reference lives with the code it configures, and the design behind all
 of it is in [docs/how-v2-works.md](docs/how-v2-works.md).
@@ -632,15 +675,26 @@ A tool that reports "nothing changed" looks exactly like a tool that is broken,
 and there is no way to tell the two apart from the outside. So:
 
 **It has to prove it still catches things.** `staysfixed check --selfcheck`
-builds twelve tiny products — each a real repository with a working commit and an
-uncommitted change on top, which is the shape an agent actually points this tool
-at — and requires the engine to behave on every one. Eight are breaks it must
-catch. Three are the other half of the same promise: pairs that must produce **no
-findings at all**, because a tool that cries wolf gets switched off, and a tool
-that is switched off catches nothing. The twelfth is the third kind, added on
-2026-08-30: a product so unsteady that the comparison is thrown away before it
-happens, where the only correct answer is that this run says **nothing** — and
-saying "nothing changed" there is the worst thing the tool can do.
+builds seventeen tiny products — each a real repository with a working commit and
+an uncommitted change on top, which is the shape an agent actually points this
+tool at — and requires the engine to behave on every one.
+
+- **Twelve are breaks it must catch**: a route that starts failing, a field
+  dropped from a reply, a different exit code, a file that is no longer written, a
+  door removed from a desktop app, a total quietly rounded, a break buried in the
+  middle of a huge output, a value that used to be steady and is now random, a
+  crash that only shows in what the program said, a charge that moved where
+  nothing in the address mentions money, a run that could only compare half of
+  itself and has to say which half, and a run whose own record could not be saved.
+- **Four are the other half of the same promise**: pairs that must produce **no
+  findings at all** — two identical builds, a product that wobbles, a build that
+  takes ten times longer, and a journey nothing could walk, which has to be named
+  as a hole rather than counted as clean. A tool that cries wolf gets switched
+  off, and a tool that is switched off catches nothing.
+- **One is the third kind**: a product so unsteady that the comparison is thrown
+  away before it happens, where the only correct answer is that this run says
+  **nothing** — and saying "nothing changed" there is the worst thing the tool can
+  do.
 
 **And it has to be honest when it cannot tell.** A case that misbehaves is built
 again from scratch and run again before that becomes an accusation. Fail twice
@@ -654,9 +708,10 @@ nothing on a busy laptop. The cause was found and removed — see
 the next machine-shaped thing to creep in lands as "nobody knows" rather than as
 a false accusation people learn to ignore. Measured on 2026-08-30: eleven of
 eleven, three times running, with the project's own suite running in parallel and
-the machine's load average between 227 and 334; and after the second sweep of
-silences, twelve of twelve, three times running, with the suite in parallel again
-and the load average between 208 and 343.
+the machine's load average between 227 and 334; then twelve of twelve after the
+second sweep of silences, three times running, with the suite in parallel again
+and the load average between 208 and 343; and finally **seventeen of seventeen**,
+with the suite in parallel, at the end of the same day.
 
 **The unstable app.** `fixtures/unstable-app` is a page built to be impossible to
 observe consistently: a clock ticking ten times a second, an endless spinner, a
@@ -729,26 +784,32 @@ Honestly, so you know before you invest an afternoon.
   when you ship. What they cannot do is read the agent's mind. The five sealed
   classes are the answer to that: in the places where being wrong is expensive,
   no judgement is accepted from any agent at all.
-- **Real phones cannot be paired.** No paired run is possible on a device in your
-  hand. Real iPhones and real Android handsets fall back to comparing against the
-  stored record, and say so out loud on every run.
-- **Native Windows cannot run two builds at once, even in principle,** because
-  Windows shows one desktop at a time.
+- **Real phones cannot be paired, and the phone surfaces are the newest thing
+  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
+  you trust a clean result.
 - **It is not every possible state.** "Deep" means every door the code exposes and
-  every journey your suite already walks. Nothing can enumerate every state, and
-  any tool claiming otherwise is lying. The coverage ledger names the doors it has
-  never opened, so the hole is visible instead of pretended away.
+  every journey it was given. Nothing can enumerate every state, and any tool
+  claiming otherwise is lying. The coverage ledger names the doors it has never
+  opened, so the hole is visible instead of pretended away.
+- **Your own test suite is not walked for you yet.** The code that harvests a
+  project's existing tests as journeys is written and tested in
+  `src/v2/journeys/`, and nothing on the check path calls it. Ask for it —
+  `--journeys suite`, or `journeys: "suite"` over MCP — and you are told that, by
+  name, rather than being given a clean result about steps it silently chose
+  instead. Today the steps come from what each adapter reads out of your source
+  and from a journeys file you point it at.
 - **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
   differently on every system. Pixels are evidence now rather than the accusation,
   which makes this matter far less than it did — but it has not gone away.
-- **Phones cannot be paired, and the iPhone is not covered yet.** Android runs on
-  an emulator against the stored record, which is weaker than a paired run and
-  says so every time. The iOS simulator is designed and not built. If you ship a
-  phone app, ask `doctor` what it is actually covering before you trust a clean
-  result — it will tell you plainly rather than let a green run mean less than it
-  looks like.
 - **Native Windows shows one desktop, so two builds cannot run at once even in
   principle.** Runs are one after the other and the same-minute guarantee is
   weaker there than on any platform. If your Windows product is Electron — most