staysfixed 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -8,6 +8,107 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Nothing yet.
 
+## [0.10.0] — 2026-08-31
+
+The night the four surfaces nobody had pointed it at were pointed at it, and the biggest
+remaining lie in the coverage ledger was closed.
+
+### Fixed — the ledger said things had been checked that had not
+
+- **Knocking counted as walking.** A door counted as walked because a step said it knocked on
+  it, whatever came back. So a route the source declares and the running build answers 404 to
+  was counted as covered — and behind a sign-in wall, where every request is bounced to
+  /login, every door in the product counted as walked and the run came back clean. What
+  answered was on the record all along. **404, 405, 410 and 501** now leave the door shut and
+  say that the source and the build disagree about whether it exists. **A redirect** is walked
+  — the bounce is real behaviour — but named as a bounce, and when every door that answered
+  did it, the run says so: that is what a sign-in wall looks like from outside. **A 500 is
+  still walked**, deliberately: the route exists and it broke, which is what a check is for.
+- **A product that never started was reported as twelve regressions.** A server that will not
+  boot produces a difference at every address it used to answer at, and not one of them said
+  the server had not started. The verdict leads with the cause now.
+- **A build older than its source passed as "nothing that worked has changed".** This tool
+  runs your product and never builds it, so `node dist/server.js` runs yesterday's build
+  against today's code and compares it against a reference cut from the same stale output. It
+  says so now. Following `npm run start` down into package.json is what made it fire at all.
+
+### Added — the headline feature actually runs
+
+- **Guards run on `staysfixed check`**, and over MCP, whenever the settings give an address to
+  open. A guard that fails becomes a finding **sealed by name**, which no agent may wave
+  through. Where there is no address to open it still says so, and names the one line that
+  would change it.
+
+### Fixed — it asked for what it had already been given
+
+- **`doctor` asked every adapter with an EMPTY config** unless the settings were JSON — and
+  `init` writes JavaScript. So on almost every project it asked for the very thing the
+  settings already named, and one sentence managed to say an app was present and missing at
+  once. It reads the few values it needs out of the text now, scoped per block, without
+  running anybody's code.
+- **`ios.app` was invisible**: the lookup only ever searched for `xcworkspace`, while this
+  tool's own advice says to name the built app under `ios.app`.
+
+### Fixed — noise that buried the news
+
+- **A bundler renames its output whenever the source changes**, so one edit produced four
+  extra findings, all of them chunk filenames, with the real change underneath. Normalised
+  inside a bundler's own asset paths only — a standalone content hash still changes and still
+  shows.
+- **On a monorepo `init` announced five products and wrote settings for one.** What is
+  announced and what is written now have to agree.
+
+### Still wrong, and written down rather than hidden
+
+- `init` still names a container folder (`packages/`) as a product on a workspaces monorepo.
+- An Electron check deadlocked once with no output and could not be reproduced.
+- The Windows surface is reachable and signed in but its screen is locked, so nothing can be
+  driven there yet.
+
+## [0.9.1] — 2026-08-30
+
+Eleven more, from the same hunt that produced 0.9.0 — the findings it had already paid for.
+Every one of these was decided by reading the code rather than by building another product to
+reproduce it; the ones that genuinely need a Next.js app or a monorepo are written down and
+left, because guessing at them would be worse.
+
+### Fixed
+
+- **Every API shape change on every project was sealed as LOSING DATA**, permanently, and no
+  agent could wave any of it through. The classifier reads the words in a finding — and it
+  was reading the difference's *description*, which is the TOOL's sentence, identical on every
+  finding that channel makes: "a renamed or dropped field shows up on its own". `dropped` is
+  a data-loss word. A seal is decided by what the PRODUCT said now — its addresses, its
+  values, its journey names — never by vocabulary no user wrote and nobody can change. A real
+  deletion still seals.
+- **`ship` printed no coverage caveat at all**, in text or `--json`. It is the command that
+  decides what "working" MEANS from that moment on, which makes it the last place that should
+  stay quiet about what the check never walked. It says it now, in the same breath as the
+  good news, exactly as every other surface does.
+- **`init` said "Nothing is being left out."** from a survey of which SURFACES this machine
+  can drive — on a project the same run reported as five of six doors never opened. And
+  `getting-started` tells the agent to repeat that sentence to the person.
+- **The MCP server echoed an agent's own strings back unbounded and kept them for ever.** A
+  megabyte of summary came back as a megabyte of tool result. Capped, and the cut says so
+  rather than quietly keeping the first part.
+- **`check --journeys recorded` reported a missing FILE called "recorded".** `--help` offers
+  the word and the MCP surface answers it honestly — written, not wired into a run yet. The
+  same question gets the same answer on both surfaces now.
+- **Guard names that said nothing were accepted**: `a b c`, `1 2 3`, `TODO fix later` and
+  `AC-101 regression check` all passed every rule. That name is the sentence somebody reads
+  when the guard fails, six months from now. Refused now — and every name that actually says
+  something still passes.
+- **Every command-line check wrote two rows** to the log `ship` reads, so any count of how
+  many checks had run was doubled.
+- **`--only` printed "everything that worked still works"** about a slice, with five of six
+  guards filtered away and one of the five failing.
+- **`ship` blessed a build nothing had ever looked at** — it matched by git commit, so an
+  uncommitted edit resolved to an earlier build that had been checked and was clean.
+- `docs/running-it-in-ci.md` told you to copy `.github/workflows/staysfixed.yml` "as it is".
+  That file is not in the npm package. It is printed in full in the page now.
+- `docs/mcp.md` still told you to fill the project path in by hand; `doctor --json` has
+  filled it in since 0.8.0, and a path filled in wrongly fails silently.
+
 ## [0.9.0] — 2026-08-30
 
 Found the same way as 0.8.0 and one better: the published build was installed as a stranger

package/docs/mcp.md

@@ -293,3 +293,16 @@ Nobody who wired that up has to change anything. Everything version 1's picture
 check did is also still reachable from the command line — `staysfixed check
 --pictures`, `staysfixed approve` — and pictures still require a person to
 approve them there, for the same reason they always did.
+
+---
+
+## You do not have to fill the path in yourself
+
+The blocks above show `/absolute/path/to/your/project` because a page cannot know where you
+are. `staysfixed doctor --json` can: its `wiring.mcp` carries the same block with `cwd`
+already set to this project, ready to paste. Ask for that rather than editing by hand — a
+path filled in wrongly fails silently, which is the worst way for this to go wrong.
+
+```sh
+npx staysfixed doctor --json | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.stringify(JSON.parse(s).wiring.mcp,null,2)))"
+```

package/docs/running-it-in-ci.md

@@ -17,7 +17,7 @@ Three files make that work:
 
 | | |
 | --- | --- |
-| `.github/workflows/staysfixed.yml` | The job. Copy it into your own project as it is. |
+| `.github/workflows/staysfixed.yml` | The job. It is printed in full at the bottom of this page, because it is not in the npm package. |
 | `src/v2/ci.js` | Works out what to compare against, runs the check, writes the report, exits with the code that decides the job. |
 | This file | What it can and cannot do up there, and why. |
 
@@ -304,3 +304,125 @@ What is **not** proved, and would only be settled by a real run:
 - How long a paired run takes on a real product. On a two-command scratch project it was
   about a second; a real project with a browser in it will be minutes, and the 30-minute
   timeout in the workflow is a guess.
+
+---
+
+## The workflow itself
+
+This file lives in the repository, not in the npm package — so if you installed Stays Fixed
+from npm you cannot copy it off disk, and the line above used to send you looking for it.
+Here it is in full. Save it as `.github/workflows/staysfixed.yml` in your own project.
+
+```yaml
+# Prove that nothing which already worked has changed — on every pull request.
+#
+# WHY A BUILD SERVER IS A GOOD PLACE FOR THIS, and not a compromise. Everything Stays Fixed
+# concludes rests on one claim: the difference was caused by the change and nothing else. A
+# fresh runner has the same fonts every time, the same operating system, nothing else
+# competing for a port, and no half-finished experiment left over from yesterday. It is a
+# better machine for this job than anybody's laptop.
+#
+# WHAT IT COMPARES AGAINST. On a pull request: the commit your branch forked from — put back
+# on this same runner with `git archive` and walked again, minutes apart. That is a full
+# paired run, and it needs nothing stored from a previous job. On a push it works down to the
+# last release, the last tag, or the commit before. Whichever it lands on is named in the job
+# summary, because they are not equally strong.
+#
+# THE ONE LINE YOU MUST NOT DELETE is `fetch-depth: 0`. A shallow checkout answers "what did
+# this branch fork from" with "this commit" — so the check would compare the build against
+# itself, find nothing, and go green. Stays Fixed catches that and refuses, but the run is
+# then worth nothing. Full history is what makes this work.
+
+name: Stays Fixed
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+# Nothing is published, released or tagged here, and no token is used for anything.
+permissions:
+  contents: read
+
+# Two runs of the same branch would be two builds on one machine fighting over ports and
+# user data directories. Sequential, never simultaneous, is a rule of the whole tool.
+concurrency:
+  group: staysfixed-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Has anything that worked changed?
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Read the paragraph above before changing this.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install
+        run: npm ci || npm install
+
+      # Only needed if anything you check is a web page. Delete these three lines for a
+      # command line tool or a library — the check will say what it could not look at either way.
+      - name: A browser to look at web pages with
+        run: npx playwright install chromium
+
+      - name: Is Stays Fixed set up in this project?
+        id: setup
+        run: |
+          # Two separate looks on purpose. One `ls` over both patterns fails whenever
+          # either of them matches nothing, which would report a configured project as
+          # unconfigured and quietly skip the whole check.
+          if ls staysfixed.config.* >/dev/null 2>&1 || ls .staysfixed/config.* >/dev/null 2>&1; then
+            echo "configured=yes" >> "$GITHUB_OUTPUT"
+          else
+            echo "configured=no" >> "$GITHUB_OUTPUT"
+            {
+              echo "## Stays Fixed"
+              echo
+              echo "This project has no Stays Fixed settings file, so **nothing was checked**."
+              echo "This job is green because nothing was claimed — not because anything was proved."
+              echo
+              echo 'Run `npx staysfixed init` in your project to set it up.'
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # Works out what to compare against, runs the check, writes the plain-English report
+      # into the job summary, and exits with the code that decides this job:
+      #
+      #   0  nothing that already worked has changed
+      #   1  something changed that nobody accounted for
+      #   2  the check could not run, or there was nothing to compare against — which is
+      #      NOT a pass, and is why this step has no `continue-on-error`
+      - name: Check
+        if: steps.setup.outputs.configured == 'yes'
+        run: |
+          # In your own project Stays Fixed is a dependency. In the Stays Fixed repository
+          # itself it is the source you are looking at. Both paths are tried so this file
+          # can be copied straight out of one into the other.
+          if [ -f node_modules/staysfixed/src/v2/ci.js ]; then
+            node node_modules/staysfixed/src/v2/ci.js
+          else
+            node src/v2/ci.js
+          fi
+
+      # Every observation both builds produced, the verdict, and what it compared against.
+      # Kept even when the job fails — especially then.
+      - name: Keep the evidence
+        if: always() && steps.setup.outputs.configured == 'yes'
+        uses: actions/upload-artifact@v4
+        with:
+          name: staysfixed-${{ github.run_id }}
+          path: |
+            .staysfixed/ci
+            .staysfixed/v2
+          if-no-files-found: ignore
+          retention-days: 14
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.9.0",
+  "version": "0.10.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 — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/guard/name.js

@@ -26,6 +26,9 @@ export const NAME_RULE_EXPLAINER =
 const MAX_LENGTH = 120;
 
 /** Words that start a test name rather than describe the app. */
+/** Words that begin a note to yourself rather than a promise about the product. */
+const PLACEHOLDERS = new Set(['todo', 'fixme', 'wip', 'xxx', 'tbd', 'temp', 'placeholder', 'hack']);
+
 const TEST_SPEAK = new Set([
   'test',
   'tests',
@@ -100,7 +103,7 @@ const VERBS = new Set([
 ]);
 
 /**
- * @typedef {'empty'|'long'|'path'|'id'|'symbols'|'caps'|'identifier'|'testspeak'|'short'} RefusalKind
+ * @typedef {'empty'|'long'|'path'|'id'|'symbols'|'caps'|'identifier'|'testspeak'|'short'|'placeholder'|'not-a-sentence'|'mostly-numbers'|'ticket'} RefusalKind
  */
 
 /**
@@ -194,6 +197,43 @@ function refuse(name) {
     };
   }
 
+  // Three words is a shape, not a sentence. `a b c`, `1 2 3`, `TODO fix later` and
+  // `AC-101 regression check` all cleared every rule above, and each of them is a guard
+  // nobody will understand in six months — which is the entire job of this name.
+  if (PLACEHOLDERS.has(first)) {
+    return {
+      kind: 'placeholder',
+      why: `Starting with "${words[0]}" is a note to yourself, not a promise about the product. Say what should still be true, so the failure reads as that sentence.`,
+    };
+  }
+
+  // A ticket reference is not a behaviour, and this file already says so about "#" and "::".
+  // `AC-101 regression check` cleared every other rule and names nothing a person could act on.
+  const ticket = words.find((w) => /^[A-Za-z]{2,}[-_]\d+$/.test(w));
+  if (ticket) {
+    return {
+      kind: 'ticket',
+      why: `"${ticket}" is a ticket reference, not a behaviour. Put it in "link" and say here what should still be true.`,
+    };
+  }
+
+  const realWords = words.filter((w) => /[A-Za-z]{4,}/.test(w));
+  if (realWords.length < 2) {
+    return {
+      kind: 'not-a-sentence',
+      why: 'That does not read as a sentence about the product — there are almost no words in it. Write what should still be true, in the words you would say out loud, like "the sidebar still collapses".',
+    };
+  }
+
+  const letters = (text.match(/[A-Za-z]/g) ?? []).length;
+  const digits = (text.match(/\d/g) ?? []).length;
+  if (digits > letters) {
+    return {
+      kind: 'mostly-numbers',
+      why: 'That is mostly numbers. A guard name is the sentence somebody reads when it fails, so put the ticket number in "link" and say the behaviour here.',
+    };
+  }
+
   return null;
 }
 

package/src/v2/check.js

@@ -326,16 +326,38 @@ export async function check(options = {}) {
     // the word "guard" exactly zero times. A tool built to catch silent breakage must not do
     // nothing silently.
     const named = await guardNames(project.root);
-    if (named.length > 0 && verdict.coverage) {
-      verdict.coverage.gaps = [
-        ...(verdict.coverage.gaps ?? []),
-        {
-          what: `${named.length} guard${named.length === 1 ? '' : 's'} written against bugs that already happened once`,
-          why:
-            `They are sealed by name, so nothing touching one can be waved through quietly — but they were not RUN on this check. ` +
-            `\`staysfixed check --guards\` walks them. ${named.map((n) => `"${n}"`).join(', ')}`,
-        },
-      ];
+    if (named.length > 0) {
+      const walked = await walkTheGuards(project.root, options);
+      if (walked.ran) {
+        // A guard that failed is a bug somebody already had, coming back. It is sealed by
+        // name — one of the five classes no agent may wave through, whatever the reason.
+        for (const bad of walked.failed) {
+          verdict.findings = [
+            ...(verdict.findings ?? []),
+            /** @type {any} */ ({
+              id: `guard-${sha256(bad.name).slice(0, 6)}`,
+              title: `A bug that was already fixed is back: ${bad.name}`,
+              why: bad.message ?? 'The guard written for it does not hold any more.',
+              class: 'named guard',
+              guard: bad.name,
+              differences: [],
+              rank: 0,
+              count: 1,
+            }),
+          ];
+        }
+        verdict.summary = `${walked.said} ${verdict.summary}`;
+        if (walked.failed.length > 0) verdict.ok = false;
+      } else if (verdict.coverage) {
+        verdict.coverage.gaps = [
+          ...(verdict.coverage.gaps ?? []),
+          {
+            what: `${named.length} guard${named.length === 1 ? '' : 's'} written against bugs that already happened once`,
+            why: `They are sealed by name, so nothing touching one can be waved through quietly — but they were not RUN on this check: ${walked.why}`,
+            unlockedBy: 'Give the settings an address to open — `url` beside `start` in the `web` block, or `electron.binary` — and every check walks them from then on.',
+          },
+        ];
+      }
     }
 
     /** @type {CheckOutcome} */
@@ -471,6 +493,21 @@ async function settle(verdict, store, product, guards) {
           : `NOTHING WAS ACTUALLY COMPARED. Every journey was walked on the build you have, and not one of them had anything on record from the build you were happy with, so there was nothing to hold them against. This is not a pass and not a failure — it is no answer. ${verdict.summary}`;
     }
 
+    // THE CAUSE FIRST, when the cause is that the product never answered.
+    //
+    // A server that will not start produces a difference at every address it used to answer
+    // at — the content type gone, the body gone, "answered at all" arriving. Measured
+    // 2026-08-31 on a product whose start command throws: twelve findings, not one of them
+    // saying the server had not started, and a person reads "12 things behave differently"
+    // and goes looking for a regression in code that is fine. The symptoms are real and they
+    // belong in the list; they are just not the news.
+    const silent = didNotAnswer(verdict);
+    if (silent.length > 0) {
+      verdict.summary =
+        `THE PRODUCT DID NOT ANSWER. ${silent.length} ${silent.length === 1 ? 'way in was' : 'ways in were'} not tried at all — ${silent.slice(0, 3).join('; ')}${silent.length > 3 ? '; and more' : ''}. Most of what follows is that one fact wearing different clothes, not ${silent.length === 1 ? 'a separate change' : 'separate changes'}: fix the start and check again before reading any of it as a regression. ` +
+        verdict.summary;
+    }
+
     // And what was NOT looked at, in the same breath as the good news, on every run
     // including the clean ones. A green verdict on a product with three hundred doors
     // nobody has ever opened is true and it is not what it looks like, and the only place
@@ -659,6 +696,45 @@ function comparedNothing(verdict) {
   return nothingToCompare >= walked ? 'no stored record' : null;
 }
 
+/**
+ * Walk the guards, if this project can be opened.
+ *
+ * Guards are the headline of this whole product — one plain-English rule per bug somebody
+ * already had — and the default command never ran them. It said so, which was better than
+ * pretending, but saying it is not doing it. Version 1 knows how to drive an app and run
+ * them; what was missing was anybody calling it from here.
+ *
+ * It needs an address it can open. Where the settings only say how to START the product,
+ * that is version 2's job and this path cannot do it — so it says so instead, and names the
+ * one line that would change it.
+ *
+ * @param {string} root
+ * @param {any} options
+ * @returns {Promise<{ran: boolean, why: string, said: string, failed: {name: string, message?: string}[]}>}
+ */
+async function walkTheGuards(root, options) {
+  try {
+    const { loadProject } = await import('../core/config.js');
+    const { runCheck } = await import('../run.js');
+    const project = await loadProject({ cwd: root, configFile: options?.configFile });
+    const run = await runCheck(project, { guardsOnly: true, writeReport: false, quiet: true, signal: options?.signal });
+    const guards = run.guards ?? [];
+    const failed = guards.filter((g) => g.status === 'failed').map((g) => ({ name: g.name, message: g.message }));
+    const held = guards.length - failed.length;
+    return {
+      ran: true,
+      why: '',
+      said:
+        failed.length === 0
+          ? `All ${guards.length} guard${guards.length === 1 ? '' : 's'} still hold.`
+          : `${failed.length} of ${guards.length} guards failed — ${failed.length === 1 ? 'a bug' : 'bugs'} that ${failed.length === 1 ? 'was' : 'were'} already fixed ${failed.length === 1 ? 'is' : 'are'} back, and no agent may wave ${failed.length === 1 ? 'it' : 'them'} through. ${held} still hold.`,
+      failed,
+    };
+  } catch (e) {
+    return { ran: false, why: messageOf(e), said: '', failed: [] };
+  }
+}
+
 /**
  * The guards this project has, by name.
  *
@@ -681,6 +757,125 @@ export async function guardNames(root) {
   }
 }
 
+/**
+ * Is the thing that ran older than the code it was built from?
+ *
+ * This tool never builds anything — deliberately, because building somebody's project is not
+ * its business. But a project whose start command runs `dist/server.js` and whose source
+ * lives in `src/` will happily run YESTERDAY's build against today's source, compare it
+ * against a reference cut from the same stale output, and answer "Nothing that worked has
+ * changed" — about code it has never once executed. Measured 2026-08-31.
+ *
+ * It cannot be fixed by building; it can be SAID, which is all a coverage gap has to do.
+ *
+ * @param {string} root
+ * @param {any} config
+ * @returns {Promise<CoverageGap|null>}
+ */
+async function builtBeforeItsSource(root, config) {
+  try {
+    let pkg = {};
+    try {
+      pkg = JSON.parse(await fsp.readFile(path.join(root, 'package.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+    const scripts = /** @type {any} */ (pkg).scripts ?? {};
+    // `npm run start` says nothing about where the product lives; the answer is one level
+    // down, in the script it runs. Following that indirection is the difference between this
+    // check firing and never firing, because `init` writes exactly `npm run start`.
+    const through = (/** @type {string} */ line) => {
+      const run = /(?:npm run|yarn|pnpm run|pnpm)\s+([\w:-]+)/.exec(line);
+      const named = run ? scripts[run[1]] : line.includes('npm start') ? scripts.start : null;
+      return `${line} ${typeof named === 'string' ? named : ''}`;
+    };
+    const starts = [
+      ...(config?.process?.commands ?? []).map((/** @type {any} */ c) => String(c?.run ?? '')),
+      String(config?.http?.start ?? ''),
+      String(config?.web?.start ?? ''),
+    ].map(through).join(' ');
+    const named = /\b(dist|build|out|lib)\b/.exec(starts);
+    const builds = typeof scripts.build === 'string';
+    if (!named || !builds) return null;
+
+    const outDir = path.join(root, named[1]);
+    const srcDir = path.join(root, 'src');
+    const [built, source] = await Promise.all([newestUnder(outDir), newestUnder(srcDir)]);
+    if (built === 0 || source === 0 || source <= built) return null;
+
+    const behind = Math.round((source - built) / 1000);
+    /** @param {number} n @param {string} unit */
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+    const howLong =
+      behind > 86400 ? plural(Math.round(behind / 86400), 'day') : behind > 3600 ? plural(Math.round(behind / 3600), 'hour') : plural(Math.max(1, Math.round(behind / 60)), 'minute');
+    return {
+      what: `What ran is older than the code it was built from — \`${named[1]}/\` is ${howLong} behind \`src/\`.`,
+      why: `This tool runs your product, it never builds it. So the build in \`${named[1]}/\` is what was walked, and your newer source was not executed at all. A clean result here says nothing whatever about the code you have just written — and the reference it was compared against was cut from the same stale output.`,
+      unlockedBy: 'Run your build before the check — `npm run build && npx staysfixed check` — or put the build into the start command in your settings.',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The newest modification time anywhere under a folder, or 0 if there is nothing there.
+ * @param {string} dir
+ * @returns {Promise<number>}
+ */
+async function newestUnder(dir) {
+  let newest = 0;
+  /** @param {string} at @param {number} depth */
+  const walk = async (at, depth) => {
+    if (depth > 6) return;
+    let entries = [];
+    try {
+      entries = await fsp.readdir(at, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = path.join(at, entry.name);
+      if (entry.isDirectory()) await walk(full, depth + 1);
+      else {
+        try {
+          const at2 = (await fsp.stat(full)).mtimeMs;
+          if (at2 > newest) newest = at2;
+        } catch {
+          // gone between the listing and the question
+        }
+      }
+    }
+  };
+  await walk(dir, 0);
+  return newest;
+}
+
+/**
+ * The ways into the product that were never tried, and why.
+ *
+ * A build that would not start does not produce one finding — it produces one at every
+ * address it used to answer at, and the real news is nowhere in the list.
+ *
+ * @param {CheckOutcome} verdict
+ * @returns {string[]}
+ */
+function didNotAnswer(verdict) {
+  /** @type {Set<string>} */
+  const said = new Set();
+  for (const finding of verdict.findings ?? []) {
+    for (const d of finding.differences ?? []) {
+      const path = String(d.path ?? '');
+      if (!path.endsWith('answered at all')) continue;
+      const name = path.split('.').slice(1, -1).join('.') || path;
+      const why = typeof d.candidate === 'string' ? d.candidate : typeof d.describe === 'string' ? d.describe : '';
+      said.add(why ? `${name} (${String(why).slice(0, 90)})` : name);
+    }
+  }
+  return [...said];
+}
+
 /**
  * Copies left behind by runs that never finished.
  *
@@ -1591,6 +1786,8 @@ async function openProject(options) {
       unlockedBy: `Fix package.json, or put the name you want in your settings file as product: '<name>'. Until then every comparison starts from nothing.`,
     });
   }
+  const stale = await builtBeforeItsSource(root, config);
+  if (stale) gaps.push(stale);
   if (storeTrouble.length > 0) {
     gaps.push({
       what: 'This run was NOT written down, so the next check has nothing from today to compare against.',
@@ -1916,6 +2113,18 @@ async function gatherJourneys({ root, config, options }) {
 
   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.
+  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.',
+      },
+    );
+  }
   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

package/src/v2/coverage.js

@@ -101,6 +101,14 @@ import { listBuilds, listCaptures, loadCapture, referencePointer } from './store
  * @property {string[]} [doors]               Door keys the journey's steps name, for steps that
  *                                            named a door with nothing to tell apart from
  *                                            another of the same name. See doorKey.
+ * @property {{door: string, status: number}[]} [onlyRedirected]
+ *                                            Doors that answered with a redirect. Walked — the
+ *                                            bounce is real behaviour — but what is behind them
+ *                                            was never seen.
+ * @property {{door: string, status: number}[]} [knockedShut]
+ *                                            Doors a step knocked on where the running build
+ *                                            answered that they are not there. Knocking is not
+ *                                            walking, and these have proved nothing.
  * @property {string[]} [doorAddresses]       Full door addresses, for steps that were specific
  *                                            enough to build one. A route step knows its verb,
  *                                            and GET /x and POST /x are two doors that share a
@@ -401,6 +409,15 @@ export function addressesTouched(observations) {
   return { paths: [...paths], byChannel };
 }
 
+/**
+ * Answers that mean the door is not there in the build that ran.
+ *
+ * A 500 is deliberately NOT here: the route exists and it broke, which is a real difference
+ * and exactly what a check is for. These four are the codes that say the thing the source
+ * declares was never reachable, so nothing has been proved about it either way.
+ */
+const NOTHING_THERE = new Set([404, 405, 410, 501]);
+
 /**
  * A walk, built from one stored capture and, when it is to hand, the journey behind it.
  *
@@ -426,8 +443,55 @@ export function walkFromCapture(capture, journey) {
     // would report POST as walked too, which is the coverage ledger lying in the one direction
     // it must never lie in.
     const named = journey.steps.filter((s) => typeof s.door === 'string' && typeof s.kind === 'string');
-    const exact = named.filter((s) => typeof s.doorDetail === 'string' && s.doorDetail !== '');
-    const byName = named.filter((s) => typeof s.doorDetail !== 'string' || s.doorDetail === '');
+
+    // KNOCKING IS NOT WALKING.
+    //
+    // A door was counted as walked because a STEP said it knocked on it — whatever came back.
+    // So a route the source declares and the running build answers 404 counted as covered; and
+    // behind a login wall, where every request is bounced to /login, every door in the product
+    // counted as walked and the run came back clean. That is the coverage ledger lying in the
+    // one direction this file says it must never lie in.
+    //
+    // What answered is on the record: the http adapter writes `api.<door>.status`. A 404, 405,
+    // 410 or 501 means the thing the code declares is not there in the build that ran, so
+    // nothing was proved about it and it stays shut.
+    const answered = new Map();
+    for (const ob of capture.observations ?? []) {
+      const found = /^api\.(.+)\.status$/.exec(String(ob?.path ?? ''));
+      if (found) answered.set(found[1], Number(ob.value));
+    }
+    /** @type {{door: string, status: number}[]} */
+    const shut = [];
+    /** @type {{door: string, status: number}[]} */
+    const bounced = [];
+    /** @param {any} s @returns {boolean} */
+    const reallyWalked = (s) => {
+      // The door is the ROUTE (`/reports`); the observation is addressed by method and route
+      // together (`api.GET /reports.status`), because GET and POST on one path are two doors.
+      // Try the composite first and the bare name after, so both shapes of step are covered.
+      const keys = [
+        typeof s.doorDetail === 'string' && s.doorDetail ? `${s.doorDetail} ${s.door}` : null,
+        typeof s.method === 'string' && s.method ? `${s.method} ${s.door}` : null,
+        String(s.door),
+      ].filter(Boolean);
+      const key = keys.find((k) => answered.has(/** @type {string} */ (k)));
+      const code = key === undefined ? undefined : answered.get(/** @type {string} */ (key));
+      // A redirect is real behaviour and it IS walked — but what you saw is the bounce, not the
+      // thing behind it. Behind a login wall every door answers 302 to /login, and the run
+      // then reports full coverage of a product it never got into.
+      if (typeof code === 'number' && code >= 300 && code < 400) {
+        bounced.push({ door: String(key), status: code });
+        return true;
+      }
+      if (typeof code !== 'number' || !NOTHING_THERE.has(code)) return true;
+      shut.push({ door: String(key), status: code });
+      return false;
+    };
+
+    const exact = named.filter((s) => typeof s.doorDetail === 'string' && s.doorDetail !== '').filter(reallyWalked);
+    const byName = named.filter((s) => typeof s.doorDetail !== 'string' || s.doorDetail === '').filter(reallyWalked);
+    if (shut.length > 0) walk.knockedShut = shut;
+    if (bounced.length > 0) walk.onlyRedirected = bounced;
     if (byName.length > 0) walk.doors = byName.map((s) => doorKey({ kind: String(s.kind), name: String(s.door) }));
     if (exact.length > 0) {
       walk.doorAddresses = exact.map((s) =>
@@ -613,6 +677,27 @@ export function buildLedger(input) {
       `${cutFunctions} functions that really did run were cut from the coverage lists to keep them readable, so up to that many of the doors counted as never opened were in fact opened. This ledger undercounts, and it undercounts by no more than ${cutFunctions}.`,
     );
   }
+  // Named, never silently dropped. A route the code declares and the build answers 404 to is
+  // not a covered route and it is not an absent one either — it is a disagreement between the
+  // source and the thing that ran, and that is worth more than most differences.
+  /** @type {Map<string, number>} */
+  const shutDoors = new Map();
+  for (const { walk } of walks) for (const d of walk.knockedShut ?? []) shutDoors.set(d.door, d.status);
+  if (shutDoors.size > 0) {
+    const listed = [...shutDoors.entries()].slice(0, 6).map(([door, code]) => `${door} answered ${code}`).join(', ');
+    caveats.push(
+      `${shutDoors.size} ${shutDoors.size === 1 ? 'door the code declares was' : 'doors the code declares were'} knocked on and answered as not being there (${listed}${shutDoors.size > 6 ? ', and more' : ''}). Knocking is not walking: nothing has been proved about ${shutDoors.size === 1 ? 'it' : 'them'}, and the source and the build that ran disagree about whether ${shutDoors.size === 1 ? 'it exists' : 'they exist'}.`,
+    );
+  }
+  /** @type {Map<string, number>} */
+  const bouncedDoors = new Map();
+  for (const { walk } of walks) for (const d of walk.onlyRedirected ?? []) bouncedDoors.set(d.door, d.status);
+  if (bouncedDoors.size > 0) {
+    const all = bouncedDoors.size >= Math.max(1, opened);
+    caveats.push(
+      `${bouncedDoors.size} ${bouncedDoors.size === 1 ? 'door' : 'doors'} answered with a redirect rather than with ${bouncedDoors.size === 1 ? 'a page' : 'pages'} — ${[...bouncedDoors.entries()].slice(0, 5).map(([door, code]) => `${door} answered ${code}`).join(', ')}${bouncedDoors.size > 5 ? ', and more' : ''}. What was seen is the bounce, not what is behind it.${all ? ' EVERY door that answered did this, which is what a sign-in wall looks like from out here: this run has not been inside the product at all.' : ''}`,
+    );
+  }
   if (input.doors.length === 0) {
     caveats.push('No doors are known at all, so this ledger cannot say what is uncovered — which is not the same as there being nothing uncovered.');
   }

package/src/v2/doctor.js

@@ -900,6 +900,18 @@ async function phoneApps(root, configFile) {
     return found ? { where: found[1], how: `your settings name it under ${key}` } : null;
   };
 
+  /**
+   * A named key whose value has to look right, so one settings word cannot be mistaken for
+   * another block's.
+   * @param {string} key
+   * @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;
+  };
+
   /**
    * @param {string[]} folders
    * @param {(name: string) => boolean} wanted
@@ -933,6 +945,14 @@ async function phoneApps(root, configFile) {
       : null);
 
   const ios =
+    // `ios.app` FIRST, because that is the key the adapter reads and the key this very file
+    // tells people to write: "name the built .app in your settings under ios.app". It then
+    // looked only for `xcworkspace`, so a settings file naming a real built app was invisible
+    // and doctor answered "no iPhone app was found in this project, and the settings do not
+    // 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')) ??
     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'))
@@ -1065,6 +1085,16 @@ async function askTheAdapters(root) {
     // Read as text and parsed only when it is JSON. Doctor never runs a person's code to
     // answer a question about their machine, and a settings file may be JavaScript.
     if (file && file.endsWith('.json')) config = JSON.parse(readFileSync(file, 'utf8'));
+    // But "not JSON" was being treated as "says nothing", and `init` writes JavaScript — so
+    // for almost every project every adapter was asked what it needs while being handed an
+    // EMPTY config. It then asked for the very thing the settings already named: a project
+    // whose settings pointed at a real built TerminalDeck.app was told, in one sentence,
+    // "the app is here. What is missing is a built iPhone app to check". Measured 2026-08-31.
+    //
+    // The few values the adapters need to answer honestly are read out of the TEXT instead,
+    // scoped to their own block so one block's `app` can never be read as another's. Still no
+    // code is run, which was the whole point of the rule.
+    else if (file) config = { ...config, ...settingsFromText(readFileSync(file, 'utf8')) };
   } catch {
     config = {};
   }
@@ -1384,6 +1414,54 @@ export function readHostProbe(name, alive, look) {
   return report;
 }
 
+/**
+ * The handful of settings an adapter needs to say what it is missing, read out of a
+ * JavaScript settings file WITHOUT running it.
+ *
+ * Scoped per block on purpose: `app` means one thing under `ios` and nothing under `web`, and
+ * a flat search would hand the wrong path to the wrong adapter.
+ *
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+function settingsFromText(text) {
+  const clean = withoutComments(text);
+  /** @type {Record<string, any>} */
+  const out = {};
+  /** @type {Record<string, string[]>} */
+  const wanted = {
+    ios: ['app'],
+    android: ['apk', 'package'],
+    electron: ['binary'],
+    web: ['url', 'start'],
+    http: ['start', 'url'],
+  };
+  for (const [block, keys] of Object.entries(wanted)) {
+    const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(clean);
+    if (!at) continue;
+    // The block's own text: from its brace to the matching one, counted rather than guessed,
+    // so a nested object cannot end the block early.
+    let depth = 0;
+    let end = at.index + at[0].length;
+    for (; end < clean.length; end += 1) {
+      if (clean[end] === '{') depth += 1;
+      else if (clean[end] === '}') {
+        if (depth === 0) break;
+        depth -= 1;
+      }
+    }
+    const inside = clean.slice(at.index + at[0].length, end);
+    /** @type {Record<string, string>} */
+    const found = {};
+    for (const key of keys) {
+      const hit = new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(inside);
+      if (hit) found[key] = hit[1];
+    }
+    if (Object.keys(found).length > 0) out[block] = found;
+  }
+  return out;
+}
+
 /**
  * Host names out of ~/.ssh/config. Patterns are skipped: `Host *` is a rule, not
  * a machine, and dialling it would be meaningless.
@@ -1704,7 +1782,14 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
             ? 'Cannot run here: no usable iOS runtime was found, so there is no simulator to boot the app on.'
             : iosReady
               ? `Covered on the simulator, against the stored record. It boots ${phones.ios.where} on a simulator of its own and reads what each control on the screen is and does. A real iPhone in your hand cannot be compared side by side and never will be — two builds cannot exist on it at once.`
-              : `The simulator is here and the app is here. What is missing is ${plainList(iosWants.map((n) => n.what))}, so a clean result would cover less than it looks like.`,
+              : // "and the app is here" was said because a PATH was found, while the adapter was
+                // still asking for a built app — so one sentence claimed the app was present and
+                // missing at once. Measured 2026-08-31 on a settings file pointing at a
+                // TerminalDeck.app that turned out to be an empty folder left by an old build.
+                // A path is not a bundle, and only the adapter can tell the difference.
+                iosWants.some((n) => /built iPhone app/i.test(String(n.what)))
+                ? `The simulator is here and the settings name an app, but there is no built app bundle at that path — an empty folder from an old build looks exactly like this. What is missing is ${plainList(iosWants.map((n) => n.what))}.`
+                : `The simulator is here and the app is here. What is missing is ${plainList(iosWants.map((n) => n.what))}, so a clean result would cover less than it looks like.`,
     canCheck: iosReady || iosPartly ? [...withoutADriver, 'meaning', 'pixels'] : [],
     cannotCheck: iosReady || iosPartly ? [] : CHANNELS.map((c) => c.id),
     needs:

package/src/v2/init.js

@@ -1579,7 +1579,14 @@ function whatItCovers(readiness) {
   else parts.push('Right now a check here covers nothing in full.');
   if (waiting.length > 0) parts.push(`${plainList(waiting, true)} ${waiting.length === 1 ? 'is' : 'are'} not covered yet, and the list below says exactly what is in the way and who has to do it.`);
   if (notCovered.length > 0) parts.push(`${plainList(notCovered, true)} ${notCovered.length === 1 ? 'is' : 'are'} not checked at all, so a clean result says nothing whatever about ${notCovered.length === 1 ? 'it' : 'them'}.`);
-  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) parts.push('Nothing is being left out.');
+  // "on this machine", because that is the only thing this sentence knows. It is built from
+  // SURFACES — which kinds of product can be watched here — and says nothing whatever about
+  // how much of this project a run actually walks. Unqualified, it read as a coverage
+  // promise, and `getting-started` tells the agent to repeat it to the person: measured
+  // 2026-08-30 on a project the same run reported as five of six doors never opened.
+  if (partly.length === 0 && notCovered.length === 0 && covered.length > 0) {
+    parts.push('Nothing is being left out on this machine — though how much of the project a run actually walks is a separate question, and every check answers it.');
+  }
 
   // The hole that never closes, named with the language that causes it. "Not covered yet"
   // reads as a job somebody will get to; this one is nobody's job and saying so is the
@@ -1800,7 +1807,21 @@ export async function run(ctx) {
   }
 
   blank();
+  // What was ANNOUNCED and what was WRITTEN have to agree. On a workspaces monorepo this
+  // said "can be checked here now" about four things — including a folder that is only a
+  // container and holds no product at all — and then wrote one settings file describing one
+  // product. Measured 2026-08-31. Everything above is what was FOUND; this says what is
+  // actually covered, and how to cover the rest.
+  const others = (result.plan?.readiness ?? [])
+    .map((/** @type {any} */ r) => String(r.product ?? ''))
+    .filter((/** @type {string} */ n, /** @type {number} */ i, /** @type {string[]} */ all) => n !== '' && all.indexOf(n) === i);
   if (result.written.length > 0) ok(`Written: ${result.written.map((f) => shortPath(f)).join(', ')}`);
+  if (others.length > 1) {
+    warn(
+      `Those settings describe ONE product. ${others.length} were found here (${others.join(', ')}), and the others are not covered by this file. ` +
+        'Run `staysfixed init` from inside each of the others to give it its own settings, and check it from there.',
+    );
+  }
   if (result.kept.length > 0) warn(`Left exactly as it was: ${result.kept.map((f) => shortPath(f)).join(', ')}`);
   for (const problem of result.problems) fail(problem);
 

package/src/v2/mcp/tools.js

@@ -1661,7 +1661,14 @@ function problem(message) {
 function text(v) {
   if (typeof v !== 'string') return null;
   const s = v.trim();
-  return s === '' ? null : s;
+  if (s === '') return null;
+  // Capped, because every one of these is a string an AGENT chose and several of them are
+  // echoed straight back in the reply and then written into the store for ever. A megabyte
+  // of summary came back as a megabyte of tool result and stayed there. Nothing legitimate
+  // here is long: a reason, a finding id, a surface name. Cutting says so out loud rather
+  // than quietly keeping the first part.
+  const MOST = 4000;
+  return s.length <= MOST ? s : `${s.slice(0, MOST)} … (cut here: this was ${s.length} characters, and nothing this tool asks for is that long)`;
 }
 
 /**

package/src/v2/normalise.js

@@ -114,6 +114,17 @@ export const DEFAULT_RULES = [
     pattern: '\\b[0-9a-fA-F]{16,31}\\b',
     with: '<hex>',
   },
+  {
+    id: 'asset.bundled',
+    kind: 'replace',
+    what: 'The hash in a bundler\'s own asset filename — /_next/static/chunks/main-9f2c1a.js, /assets/index-4b8e21.css, app.7d3f9a1c.js.',
+    why:
+      'A bundler renames its output whenever the source changes, so editing one line renames several files. Measured on a Next.js app: one source edit produced four extra findings, all of them chunk filenames, and the change a person actually made was underneath them. The rename is not news — the code change is, and that is reported on its own.',
+    wouldHide:
+      'A deliberate change to an asset filename, which nobody makes by hand. Deliberately narrow: the hash is only taken inside a path that a bundler owns, so a content hash anywhere else still changes and still shows — see id.hex, which leaves 32-and-longer hex alone for exactly that reason.',
+    pattern: '(/_next/static/[^"\'\\s]*?|/assets/[^"\'\\s]*?|\\b[\\w.-]+)[.-][0-9a-fA-F]{6,}(\\.(?:js|mjs|css|map))',
+    with: '$1.<asset>$2',
+  },
   {
     id: 'id.pid',
     kind: 'replace',

package/src/v2/sealed.js

@@ -358,7 +358,13 @@ function readFinding(finding) {
   const differences = finding.differences ?? [];
   for (const d of differences) {
     add(d.path, d.path);
-    add(d.describe, d.path);
+    // NOT `d.describe`. That sentence is the TOOL's, not the product's — it explains what a
+    // channel watches and is the same on every finding that channel ever produces. The API
+    // shape channel's says "a renamed or dropped field shows up on its own", and `dropped`
+    // is a data-loss word, so every API shape change on every project was sealed as losing
+    // data, permanently, and no agent could wave any of it through. A seal has to be decided
+    // by what the PRODUCT said — its addresses, its values, its journey names — never by the
+    // tool's own vocabulary, which no user wrote and nobody can change.
     add(faceOf(d.reference), d.path);
     add(faceOf(d.candidate), d.path);
     add(d.journey, `the ${d.journey} journey`);

package/src/v2/ship.js

@@ -211,10 +211,13 @@ export async function onShip(opts = {}) {
     result.cut = cut.unchanged !== true;
     result.unchanged = cut.unchanged === true;
 
+    const missed = await whatTheCheckMissed(store);
+
     if (cut.unchanged) {
       result.lines = [
         `${product} ${release.describe}`,
         `That build was already what ${product} calls working, so nothing moved and no waivers were retired. Recording a release twice is safe.`,
+        ...(missed ? [missed] : []),
       ];
       result.summary = `${product} ${release.what} was already the reference — nothing changed.`;
       return result;
@@ -228,6 +231,8 @@ export async function onShip(opts = {}) {
       // ran only once, so part of this reference has no steadiness record behind it.
       ...(cut.stability.measuredJourneys < cut.stability.journeys ? [cut.stability.note] : []),
       'Nobody has to approve anything. The next check compares against this.',
+      // Said in the same breath as the good news, exactly as every other surface says it.
+      ...(missed ? [missed] : []),
     ];
     result.summary = cut.summary;
     return result;
@@ -247,6 +252,33 @@ export async function onShip(opts = {}) {
 
 // ---------------------------------------------------------------------------
 // What just shipped?
+/**
+ * What the last check did NOT look at, said here too.
+ *
+ * `ship` is the one command that decides what "working" MEANS from now on, and it printed no
+ * coverage caveat at all — not in the text, not in `--json`. Every other surface says it, in
+ * the same breath as the good news, because a green result on a product with doors nobody has
+ * ever opened is true and is not what it looks like. The command that turns that result into
+ * the standard is the last place that should stay quiet about it.
+ *
+ * @param {Store} store
+ * @returns {Promise<string|null>}
+ */
+async function whatTheCheckMissed(store) {
+  try {
+    const raw = JSON.parse(await fsp.readFile(path.join(store.dir, 'last-check.json'), 'utf8'));
+    const coverage = raw?.result?.coverage ?? null;
+    if (!coverage) return null;
+    const { whatWasNotChecked } = await import('./check.js');
+    const said = whatWasNotChecked(coverage);
+    return typeof said === 'string' && said.trim() ? said.trim() : null;
+  } catch {
+    // No record, or unreadable. Saying nothing is right here — inventing a caveat would be
+    // its own kind of lie.
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 
 /**