staysfixed 0.4.0 → 0.6.0

package/src/v2/adapters/source.js

@@ -748,12 +748,16 @@ function methodNames(tokens, nameAt) {
  * @param {string} opts.root                  Project root. Only ever read.
  * @param {string[]} [opts.folders]           Subfolders to read. Defaults to the usual ones.
  * @param {boolean} [opts.includeTests]       Count doors found in test files. Default false.
- * @param {number} [opts.maxFileBytes]        Skip anything bigger. Default 2MB.
+ * @param {number} [opts.maxFileBytes]        Skip anything bigger. Default 24MB — a built
+ *   bundle is a legitimate thing to read, and Terminal Deck's is 3.5MB. At the old 2MB
+ *   the whole main process was skipped and the reader then said it had found no source
+ *   at all, which is the exact shape of failure this tool exists to prevent: a silence
+ *   that reads like an all-clear.
  * @returns {Promise<ContractReading>}
  */
 export async function readContract(opts) {
   const root = path.resolve(opts.root);
-  const maxFileBytes = opts.maxFileBytes ?? 2 * 1024 * 1024;
+  const maxFileBytes = opts.maxFileBytes ?? 24 * 1024 * 1024;
   const found = await collectFiles(root, opts.folders ?? SOURCE_FOLDERS, maxFileBytes);
 
   /** @type {RawDoor[]} */
@@ -767,6 +771,12 @@ export async function readContract(opts) {
     filesRead: 0, filesSkipped: found.skipped, testFiles: 0, lexRecoveries: 0,
     typesStripped: 0, unnamed: 0, viaConstant: 0, duplicates: 0, problems: [], counts: {},
   };
+  for (const where of found.unreadable) {
+    report.problems.push(`${where} could not be opened, so any door behind it is invisible to this run.`);
+  }
+  for (const big of found.tooBig) {
+    report.problems.push(`${big} is bigger than the ${Math.round(maxFileBytes / (1024 * 1024))}MB this reader will open, so its doors were not read.`);
+  }
 
   for (const rel of found.files) {
     let text;
@@ -854,6 +864,10 @@ function describeError(error) {
  * @param {number} maxFileBytes
  */
 async function collectFiles(root, folders, maxFileBytes) {
+  /** @type {string[]} Files skipped for size, named so the gap can be reported. */
+  const tooBig = [];
+  /** @type {string[]} A folder that could not be opened at all, named for the same reason. */
+  const unreadable = [];
   /** @type {string[]} */
   const files = [];
   let skipped = 0;
@@ -864,7 +878,12 @@ async function collectFiles(root, folders, maxFileBytes) {
     let entries;
     try {
       entries = await fsp.readdir(dir, { withFileTypes: true });
-    } catch {
+    } catch (e) {
+      // A folder that will not open — a permission, a broken mount, a case-clash — used to
+      // vanish without a word, and every door behind it vanished with it. That is the same
+      // bug as the 2MB file limit wearing a different hat: fewer doors reported, and nothing
+      // anywhere saying so. Name it.
+      unreadable.push(`${path.relative(root, dir) || '.'} (${describeError(e)})`);
       return;
     }
     for (const entry of entries) {
@@ -879,8 +898,16 @@ async function collectFiles(root, folders, maxFileBytes) {
       if (!CODE_EXTENSIONS.has(path.extname(entry.name))) continue;
       if (/\.d\.[cm]?ts$/.test(entry.name)) continue;   // declarations describe, they open nothing
       try {
-        if ((await fsp.stat(full)).size > maxFileBytes) { skipped++; continue; }
-      } catch {
+        // A file too big to read is a hole, and a hole has to be named. Recording the
+        // path — not just a count — is what lets the coverage ledger say WHICH door it
+        // cannot see rather than quietly reporting fewer of them.
+        if ((await fsp.stat(full)).size > maxFileBytes) {
+          skipped++;
+          tooBig.push(path.relative(root, full));
+          continue;
+        }
+      } catch (e) {
+        unreadable.push(`${path.relative(root, full)} (${describeError(e)})`);
         continue;
       }
       files.push(path.relative(root, full));
@@ -890,7 +917,11 @@ async function collectFiles(root, folders, maxFileBytes) {
   const roots = folders.map((f) => path.join(root, f)).filter((d) => fs.existsSync(d));
   for (const dir of roots.length > 0 ? roots : [root]) await walk(dir);
   files.sort();
-  return { files, skipped };
+  // A source folder that was asked for and is not there at all is worth saying too: a typo in
+  // "folders" reads exactly like a project with no code in it.
+  const asked = folders.map((f) => path.join(root, f));
+  const present = asked.filter((d) => fs.existsSync(d));
+  return { files, skipped, tooBig, unreadable, lookedIn: present.length > 0 ? present.map((d) => path.relative(root, d)) : ['the whole project folder'] };
 }
 
 // ---------------------------------------------------------------------------
@@ -902,12 +933,18 @@ async function collectFiles(root, folders, maxFileBytes) {
  * Both layouts are handled: an app folder, where a `route` file's exported method names are
  * the verbs, and a pages/api folder, where the file itself is the route.
  *
+ * A folder that cannot be opened takes every route behind it, so it is named rather than
+ * skipped. This is the same bug as the one fixed in the file walk on 2026-08-30 — a hole that
+ * looks exactly like a project with no routes in it — and it was still here in this function.
+ *
  * @param {string} root
- * @returns {Promise<Door[]>}
+ * @returns {Promise<{doors: Door[], problems: string[]}>}
  */
 export async function readFileRoutes(root) {
   /** @type {Door[]} */
   const doors = [];
+  /** @type {string[]} */
+  const problems = [];
 
   /**
    * @param {string} base
@@ -921,7 +958,12 @@ export async function readFileRoutes(root) {
       const dir = /** @type {string} */ (stack.pop());
       /** @type {import('node:fs').Dirent[]} */
       let entries;
-      try { entries = await fsp.readdir(dir, { withFileTypes: true }); } catch { continue; }
+      try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+      } catch (e) {
+        problems.push(`${path.relative(root, dir) || '.'} could not be opened, so any route behind it is invisible to this run (${describeError(e)}).`);
+        continue;
+      }
       for (const entry of entries) {
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
@@ -972,7 +1014,7 @@ export async function readFileRoutes(root) {
     });
   }
 
-  return doors;
+  return { doors, problems };
 }
 
 /**
@@ -1162,7 +1204,10 @@ export const sourceAdapter = defineAdapter({
   /** @param {import('./contract.js').AdapterProject} project */
   async detect(project) {
     const folders = project.config?.folders ?? SOURCE_FOLDERS;
-    const found = await collectFiles(project.root, folders, 2 * 1024 * 1024);
+    // The same limit readContract uses. It was 2MB here and 24MB there, so a project
+    // whose source is one big bundle was declared to have no source at all — and then
+    // never read, even though the reader could have read it perfectly well.
+    const found = await collectFiles(project.root, folders, 24 * 1024 * 1024);
     const canStrip = typeof nodeModule.stripTypeScriptTypes === 'function';
     /** @type {import('./contract.js').Missing[]} */
     const missing = [];
@@ -1214,7 +1259,13 @@ export const sourceAdapter = defineAdapter({
    */
   async run(journey, build) {
     const reading = await readContract({ root: build.root });
-    reading.doors.push(...await readFileRoutes(build.root));
+    const fileRoutes = await readFileRoutes(build.root);
+    reading.doors.push(...fileRoutes.doors);
+    // A folder the route walk could not open is a hole in the door list, and the door list is
+    // the channel that catches doors disappearing. It goes where every other reading problem
+    // goes: into the report, which becomes an observation of its own, so it shows up as a
+    // difference the moment it starts or stops happening.
+    reading.report.problems.push(...fileRoutes.problems);
     reading.doors.push(...await readPackageCommands(build.root));
     reading.report.counts = {};
     for (const found of reading.doors) {

package/src/v2/adapters/web.js

@@ -42,8 +42,8 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 
 import {
-  countBucket, defineAdapter, joinPath, notCovered, observation, sizeBucket, timeBucket,
-  trimForStorage, undoOurFootprint,
+  countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
+  timeBucket, trimForStorage, undoOurFootprint,
 } from './contract.js';
 import { copyForScratch, frozenEnvironment } from './process.js';
 import { freePort, looksDestructive, waitForServer } from './http.js';
@@ -624,13 +624,13 @@ export const webAdapter = defineAdapter({
       out.push(...describeComplaints(journey, handle.consoleErrors()));
 
       out.push(
-        observation({
+        howLongItTook({
           channel: 'counters',
           path: joinPath('count', journey.name, 'how long the steps took'),
-          value: timeBucket(Date.now() - started),
-          says: `Walking the steps of "${journey.name}" took ${timeBucket(Date.now() - started)}, not counting opening the browser, which is our time and not the app's. Deliberately rough: exact timings differ on every run and would drown everything else.`,
+          ms: Date.now() - started,
+          what: `Walking the steps of "${journey.name}"`,
+          andAlso: 'This does not count opening the browser, which is our time and not the app\'s.',
           journey: journey.name,
-          surface: 'web',
         }),
       );
 

package/src/v2/cause.js

@@ -60,12 +60,17 @@ const run = promisify(execFile);
  * @property {string} [worktree]   Where it ran, when `keep` was asked for.
  */
 
-/**
- * How many of a finding's differences are worth re-checking. A finding can stand
- * for two hundred addresses; if the first handful come back the same way, the
- * two hundredth will too, and walking them all buys nothing.
- */
-const CHECK_AT_MOST = 5;
+// EVERY difference in the finding is re-checked, and there is deliberately no ceiling.
+//
+// Until 2026-08-30 this checked the first five and then said "caused by that change" about
+// the whole finding. A cluster of three hundred addresses where the first five went away and
+// the other two hundred and ninety-five did not came back PROVED — the agent then had a
+// machine-checked reason to wave the whole thing through, and the rest of the break went with
+// it. That is this tool's worst failure shape: a confident sentence covering a silence.
+//
+// The comment that used to sit here said walking them all buys nothing. It buys the claim.
+// And it costs nothing to buy: the journeys were re-walked already, the observations are in
+// the map below, and each extra difference is one lookup in it.
 
 /**
  * Prove, or disprove, that one change caused one finding.
@@ -192,7 +197,7 @@ export async function proveCause(finding, opts) {
       without.set(journey.name, indexByPath(settled.observations));
     }
 
-    const differences = finding.differences.slice(0, CHECK_AT_MOST);
+    const differences = finding.differences;
     let disappeared = 0;
     for (const d of differences) if (gone(d, without)) disappeared += 1;
 
@@ -207,7 +212,9 @@ export async function proveCause(finding, opts) {
           ? 'This finding carries no differences, so there was nothing to re-check.'
           : proved
             ? `Undoing that one change in ${hunk.file} made this go away. It is yours, and it is explained.`
-            : `This is still here with that change undone, so ${hunk.file} is not what caused it. Something else did, and nothing knows what yet.`,
+            : disappeared > 0
+              ? `Undoing that change in ${hunk.file} took away ${disappeared} of the ${differences.length} addresses in this finding and left ${differences.length - disappeared} exactly as ${differences.length - disappeared === 1 ? 'it was' : 'they were'}. So that change explains part of this and not the rest, and the rest has another cause nothing has looked for yet. It is not covered by undoing that one change.`
+              : `This is still here with that change undone, so ${hunk.file} is not what caused it. Something else did, and nothing knows what yet.`,
       hunk: { file: hunk.file, header: hunk.header },
       checked: differences.length,
       disappeared,

package/src/v2/check.js

@@ -27,7 +27,8 @@ import fsp from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { promisify } from 'node:util';
 
 import { StaysFixedError, messageOf } from '../core/errors.js';
@@ -270,6 +271,7 @@ export async function check(options = {}) {
       product: project.product,
       candidate: project.candidate,
       journeys: project.journeys,
+      gaps: project.gaps,
       walk: project.walk,
       cwd: project.root,
       bootReference: project.bootReference,
@@ -695,6 +697,10 @@ function short(value) {
  * @property {BuildFingerprint} candidate
  * @property {string} [against]   The reference build's own id, once a name has been resolved.
  * @property {Journey[]} journeys
+ * @property {CoverageGap[]} gaps   Holes found while working out WHAT to walk, before a
+ *   single journey ran. An adapter that fell over listing its journeys belongs here, and it
+ *   has to reach the verdict: a channel that silently dropped out is the worst thing this
+ *   tool can do.
  * @property {import('./run.js').Walker} walk
  * @property {(reference: BuildFingerprint, ctx: {events?: CheckEvents, signal?: AbortSignal}) => Promise<LiveBuild|null>} bootReference
  * @property {(capture: Capture) => Capture} normalise
@@ -732,17 +738,11 @@ async function openProject(options) {
   const evidenceDir = path.join(scratch, 'evidence');
   await fsp.mkdir(evidenceDir, { recursive: true });
 
-  const candidate = await fingerprintWorkingTree(root, product);
-  await saveBuild(store, candidate);
-
-  // A name like "HEAD", "v0.13.0" or a branch is what a person types; the store only knows
-  // builds. Turning the name into a commit here, and putting that commit in the store, is
-  // what lets a check be aimed at any point in history without every commit having been
-  // walked before. Without it "HEAD" matches nothing and the check reports itself blocked.
-  const reference = options.against ? await fingerprintCommit(root, product, options.against) : null;
-  if (reference) await saveBuild(store, reference);
-
-  const journeys = narrowToTarget(await gatherJourneys({ root, config, options }), aim);
+  // Working out what there is to walk comes FIRST, before anything is asked of git. Somebody
+  // standing in a folder they have not set up yet should be told to run `init`, not told
+  // about a git requirement they have no reason to care about yet.
+  const gathered = await gatherJourneys({ root, config, options });
+  const journeys = narrowToTarget(gathered.journeys, aim);
   if (journeys.length === 0) {
     await fsp.rm(scratch, { recursive: true, force: true });
     // Two different situations wear the same symptom, and the difference is the
@@ -762,6 +762,16 @@ async function openProject(options) {
     });
   }
 
+  const candidate = await fingerprintWorkingTree(root, product);
+  await saveBuild(store, candidate);
+
+  // A name like "HEAD", "v0.13.0" or a branch is what a person types; the store only knows
+  // builds. Turning the name into a commit here, and putting that commit in the store, is
+  // what lets a check be aimed at any point in history without every commit having been
+  // walked before. Without it "HEAD" matches nothing and the check reports itself blocked.
+  const reference = options.against ? await fingerprintCommit(root, product, options.against) : null;
+  if (reference) await saveBuild(store, reference);
+
   const rules = mergeRules(DEFAULT_RULES, [
     ...machineRules({ root, home: os.homedir(), tmp: os.tmpdir() }),
     ...machineRules({ root: scratch }),
@@ -793,6 +803,7 @@ async function openProject(options) {
     candidate,
     against: reference ? reference.id : options.against,
     journeys,
+    gaps: gathered.gaps,
     walk,
     bootReference,
     normalise,
@@ -1063,11 +1074,13 @@ function adapterFor(journey) {
  * all, and it is the only channel that sees a door nobody has ever walked through.
  *
  * @param {{root: string, config: Record<string, any>, options: CheckOptions}} a
- * @returns {Promise<Journey[]>}
+ * @returns {Promise<{journeys: Journey[], gaps: CoverageGap[]}>}
  */
 async function gatherJourneys({ root, config, options }) {
   /** @type {Journey[]} */
   const journeys = [];
+  /** @type {CoverageGap[]} */
+  const gaps = [];
 
   const named = options.journeys && options.journeys !== 'code' && options.journeys !== 'config' ? options.journeys : null;
   if (named) journeys.push(...(await readJourneyFile(path.resolve(root, named))));
@@ -1082,21 +1095,44 @@ async function gatherJourneys({ root, config, options }) {
     let detection;
     try {
       detection = await adapter.detect(project);
-    } catch {
+    } catch (e) {
+      // BOTH of these used to be swallowed without a word, and that is the same shape of
+      // failure as the source reader skipping a 3.5MB bundle: a whole channel drops out of
+      // the run, nothing is walked, and the verdict says "nothing that worked has changed".
+      // An adapter that FALLS OVER is a hole. An adapter that says "this is not my kind of
+      // project" is not, which is why only the throw is recorded here.
+      gaps.push({
+        what: `Nothing was checked through the "${adapter.name}" adapter, because it could not even work out whether it applies to this project.`,
+        why: messageOf(e),
+        unlockedBy: `Run \`staysfixed doctor\` to see what the ${adapter.name} adapter needs here. Until then, anything only it can see is not being watched.`,
+      });
       continue;
     }
     if (!detection.applies) continue;
     if (adapter !== sourceAdapter && named) continue;
     try {
       journeys.push(...(await adapter.journeys(project)));
-    } catch {
-      // An adapter that cannot list its journeys contributes none. It is not a reason to
-      // throw away the ones that could.
+    } catch (e) {
+      gaps.push({
+        what: `The "${adapter.name}" adapter applies to this project and could not say what it would walk, so it walked nothing.`,
+        why: messageOf(e),
+        unlockedBy: `Fix what it is complaining about, or name the steps yourself in a journeys file. This is a hole, not a pass.`,
+      });
     }
   }
 
   const only = options.only ?? [];
   const chosen = only.length > 0 ? journeys.filter((j) => only.some((n) => j.name === n || j.name.includes(n))) : journeys;
+  if (only.length > 0) {
+    for (const wanted of only) {
+      if (chosen.some((j) => j.name === wanted || j.name.includes(wanted))) continue;
+      gaps.push({
+        what: `You asked for the journey "${wanted}" and there is no journey by that name, so it was not walked.`,
+        why: 'A name that matches nothing narrows the run to nothing rather than to what you meant.',
+        unlockedBy: `The journeys this project has are: ${journeys.map((j) => j.name).slice(0, 12).join(', ') || 'none'}.`,
+      });
+    }
+  }
 
   // Two journeys with one name would write into one another's records.
   /** @type {Journey[]} */
@@ -1107,7 +1143,7 @@ async function gatherJourneys({ root, config, options }) {
     seen.add(j.name);
     out.push(j);
   }
-  return out;
+  return { journeys: out, gaps };
 }
 
 /**
@@ -1188,19 +1224,46 @@ async function readConfig(configFile) {
  */
 async function fingerprintWorkingTree(root, product) {
   const sha = await git(root, ['rev-parse', 'HEAD']);
-  const diff = (await git(root, ['diff', 'HEAD'])) ?? '';
-  const untracked = (await git(root, ['ls-files', '--others', '--exclude-standard'])) ?? '';
-  const dirty = diff.trim() !== '' || untracked.trim() !== '';
+  if (!sha) {
+    // REFUSING IS THE ONLY HONEST ANSWER HERE, and the alternative is the worst bug this
+    // tool could have. Without git there is nothing to tell one build from another, so every
+    // run would be fingerprinted identically, the build you just changed would carry the same
+    // id as the build you were happy with, and comparing a build against itself produces zero
+    // differences — a permanent, confident, completely false all-clear.
+    throw new StaysFixedError(
+      'This folder is not a git repository with a commit in it, and Stays Fixed tells one build from another by what git says is in it.',
+      {
+        hint:
+          'Run it inside your project (or `git init && git commit` first). Without git every run would look like the same build, ' +
+          'and a check that compares a build against itself always comes back clean — which would be a lie, so it is refused instead.',
+      },
+    );
+  }
+  // Streamed into a hash rather than read into a string. `git diff` used to go through a
+  // buffer with a 32MB ceiling, and a diff over the ceiling made the git call FAIL — which
+  // was caught, treated as an empty diff, and the working tree was then declared clean. A
+  // big uncommitted change therefore got the id of the commit it sat on top of; if that
+  // commit was the reference, the check compared the build against itself and reported that
+  // nothing had changed. Nothing about a diff's size may ever decide whether a change exists.
+  const diff = await gitDigest(root, ['diff', 'HEAD']);
+  const untracked = await gitDigest(root, ['ls-files', '--others', '--exclude-standard']);
+  if (!diff.ok || !untracked.ok) {
+    throw new StaysFixedError(
+      `Git could not say what has changed in this working tree, so there is no way to tell this build apart from the last one. ${diff.why ?? untracked.why ?? ''}`.trim(),
+      { hint: 'Fix that and run again. Guessing "nothing has changed" here would make every later answer worthless.' },
+    );
+  }
+  const dirty = !diff.empty || !untracked.empty;
   const version = await packageVersion(root);
 
   /** @type {BuildFingerprint} */
   const build = {
-    id: dirty ? `work-${sha256(`${sha ?? ''}\n${diff}\n${untracked}`).slice(0, 12)}` : `git-${(sha ?? 'unknown').slice(0, 12)}`,
+    id: dirty ? `work-${sha256(`${sha}\n${diff.digest}\n${untracked.digest}`).slice(0, 12)}` : `git-${sha.slice(0, 12)}`,
     product,
     platform: `${process.platform}-${process.arch}`,
     builtAt: new Date().toISOString(),
   };
-  if (sha) build.gitSha = sha;
+  build.gitSha = sha;
   if (version) build.version = dirty ? `${version} with uncommitted changes` : version;
   if (dirty) build.dirty = true;
   const branch = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
@@ -1276,6 +1339,41 @@ async function exportBuild(root, reference, scratch) {
 // Small things
 // ---------------------------------------------------------------------------
 
+/**
+ * Run a git command and hash its output as it arrives, without ever holding it in memory.
+ *
+ * This exists because of a specific failure: reading `git diff` into a string through a
+ * buffer with a ceiling turns "your change is enormous" into "the command failed", and the
+ * caller then has to guess. A hash costs nothing, has no ceiling, and answers the only two
+ * questions the fingerprint asks — was there anything, and was it the same thing as last time.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {Promise<{ok: boolean, empty: boolean, digest: string, why?: string}>}
+ */
+function gitDigest(cwd, args) {
+  return new Promise((resolve) => {
+    const hash = createHash('sha256');
+    let bytes = 0;
+    /** @type {string[]} */
+    const complaints = [];
+    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.on('data', (chunk) => {
+      bytes += chunk.length;
+      hash.update(chunk);
+    });
+    child.stderr.on('data', (chunk) => complaints.push(String(chunk)));
+    child.on('error', (e) => resolve({ ok: false, empty: true, digest: '', why: messageOf(e) }));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        resolve({ ok: false, empty: true, digest: '', why: complaints.join(' ').trim() || `git exited with ${code}` });
+        return;
+      }
+      resolve({ ok: true, empty: bytes === 0, digest: hash.digest('hex') });
+    });
+  });
+}
+
 /**
  * @param {string} cwd
  * @param {string[]} args

package/src/v2/cli.js

@@ -344,9 +344,15 @@ async function runSelfCheck(ctx, asJson) {
   const { selfcheck } = await import('./selfcheck.js');
   const result = await selfcheck({ only: ctx.list('only') });
 
+  // Three outcomes, not two. "Every break was caught", "a break got through", and "one case
+  // behaved on the second run and not the first, so nobody knows" are different facts, and
+  // the third one has to be able to say so instead of being rounded to either neighbour.
+  const untellable = result.cases.filter((one) => one.verdict === 'could not tell');
+  const reallyWrong = result.cases.filter((one) => !one.caught && one.verdict !== 'could not tell');
+
   if (asJson) {
     process.stdout.write(JSON.stringify(result) + '\n');
-    return result.passed ? EXIT.ok : EXIT.failed;
+    return result.passed ? EXIT.ok : reallyWrong.length > 0 ? EXIT.failed : EXIT.error;
   }
 
   heading('Stays Fixed — checking that it can still catch things');
@@ -379,8 +385,15 @@ async function runSelfCheck(ctx, asJson) {
     ok(`All ${result.cases.length} of them behaved: every break caught, every clean pair silent.`);
     return EXIT.ok;
   }
-  const wrong = result.cases.filter((one) => !one.caught).length;
-  fail(`It got ${wrong} of ${result.cases.length} wrong. Until that is fixed, a clean check means nothing.`);
+  if (reallyWrong.length === 0) {
+    fail(
+      `${untellable.length} of ${result.cases.length} could not be told either way: ${untellable.length === 1 ? 'it' : 'they'} behaved on the second run and not on the first. ` +
+        'That is not a pass and not a failure — it is no answer. Run it again on a machine that is not busy.',
+    );
+    return EXIT.error;
+  }
+  fail(`It got ${reallyWrong.length} of ${result.cases.length} wrong, twice in a row each. Until that is fixed, a clean check means nothing.`);
+  if (untellable.length > 0) fail(`${untellable.length} more could not be told either way.`);
   return EXIT.failed;
 }
 

package/src/v2/coverage.js

@@ -729,8 +729,16 @@ export async function ledger(store, product, opts = {}) {
     caveats.push('The doors were handed in by the code reader as this ledger was drawn up, so it knows about doors added since the last run.');
   } else if (opts.root) {
     const reading = await readContract({ root: opts.root });
-    reading.doors.push(...(await readFileRoutes(opts.root)));
+    const fileRoutes = await readFileRoutes(opts.root);
+    reading.doors.push(...fileRoutes.doors);
     reading.doors.push(...(await readPackageCommands(opts.root)));
+    for (const problem of fileRoutes.problems) {
+      holes.push({
+        what: problem,
+        why: 'Doors nobody can see are not counted here, so this ledger is smaller than the product is.',
+        unlockedBy: 'Make that folder readable by whoever runs the check.',
+      });
+    }
     doors = reading.doors.map(doorFact);
     caveats.push(`The code was read as this ledger was drawn up: ${reading.report.filesRead} files, ${reading.doors.length} doors, and nothing was run.`);
   } else {

package/src/v2/detect.js

@@ -805,7 +805,7 @@ async function readTheSource(root) {
     const reading = await readContract({ root });
     const fileRoutes = await readFileRoutes(root);
     const commands = await readPackageCommands(root);
-    const doors = [...reading.doors, ...fileRoutes, ...commands];
+    const doors = [...reading.doors, ...fileRoutes.doors, ...commands];
     /** @type {Record<string, number>} */
     const counts = {};
     for (const door of doors) counts[door.kind] = (counts[door.kind] ?? 0) + 1;

package/src/v2/doctor.js

@@ -32,7 +32,7 @@ import { existsSync, accessSync, readFileSync, readdirSync, constants as fsConst
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
-import { findConfigFile } from '../core/paths.js';
+import { findConfigFile, rootForConfig } from '../core/paths.js';
 import { platformTag } from '../drive/find.js';
 import { isRepo } from '../core/git.js';
 import { surveyBrowsers, INSTALL_COMMAND, PORT_NEVER_USE } from './browsers.js';
@@ -174,7 +174,12 @@ export async function capabilities(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const offline = opts.offline === true || process.env.STAYSFIXED_OFFLINE !== undefined;
   const configFile = opts.configFile ? path.resolve(cwd, opts.configFile) : findConfigFile(cwd);
-  const root = configFile ? path.dirname(configFile) : cwd;
+  // rootForConfig, never path.dirname: a config kept at `.staysfixed/config.json` — one of
+  // the six names this tool looks for — would otherwise make the project root the
+  // `.staysfixed` folder itself, and every adapter would be asked about an empty directory.
+  // Measured on Terminal Deck: doctor reported "a built APK is still missing" with the APK
+  // sitting two folders up, and told the agent to go and build one that was already there.
+  const root = configFile ? rootForConfig(configFile) : cwd;
 
   // The browser survey comes first because three different answers below depend
   // on it, and asking this machine the same question three times would be both
@@ -258,6 +263,8 @@ const PERMANENT_LIMITS = [
   'It checks the journeys it has. It cannot enumerate every possible state, and the coverage ledger names the doors it has never opened rather than pretending they are covered.',
   'Two builds of a real phone in your hand cannot be run side by side. Real devices fall back to comparing against the stored record, and say so.',
   'If the old build can no longer be compiled, comparison falls back to the stored record from the last time it ran. That is genuinely weaker and announces itself on every run.',
+  'It will not tell you your product got slower. How long something took is recorded and printed, and never compared: a stopwatch on a shared machine measures how busy the machine is at least as much as it measures the product, so comparing it invents a slowdown every time the machine is busy. A build that HANGS is still caught, because it is stopped for taking too long and how it finished is compared exactly.',
+  'A change buried in the middle of an output larger than 64KB can be missed. The two ends are kept and compared along with the exact number of bytes discarded, so a middle that grew or shrank shows up; one that changed without changing length does not. The whole text is written to the evidence folder and the run says it only compared the ends.',
 ];
 
 /**
@@ -658,7 +665,12 @@ function findDesktopApp(cwd) {
     }
   }
 
-  const root = configFile ? path.dirname(configFile) : cwd;
+  // rootForConfig, never path.dirname: a config kept at `.staysfixed/config.json` — one of
+  // the six names this tool looks for — would otherwise make the project root the
+  // `.staysfixed` folder itself, and every adapter would be asked about an empty directory.
+  // Measured on Terminal Deck: doctor reported "a built APK is still missing" with the APK
+  // sitting two folders up, and told the agent to go and build one that was already there.
+  const root = configFile ? rootForConfig(configFile) : cwd;
   const ext = process.platform === 'darwin' ? '.app' : process.platform === 'win32' ? '.exe' : '.AppImage';
   for (const folder of ['dist', 'out', 'release', 'build']) {
     const dir = path.join(root, folder);

package/src/v2/journeys/from-routes.js

@@ -436,7 +436,9 @@ export function journeysFromDoors(doors, options = {}) {
 export async function journeysFromCode(opts) {
   const started = Date.now();
   const reading = await readContract({ root: opts.root, folders: opts.folders });
-  reading.doors.push(...(await readFileRoutes(opts.root)));
+  const fileRoutes = await readFileRoutes(opts.root);
+  reading.doors.push(...fileRoutes.doors);
+  reading.report.problems.push(...fileRoutes.problems);
   reading.doors.push(...(await readPackageCommands(opts.root)));
 
   const surface =