staysfixed 0.9.1 → 0.11.0

package/src/v2/check.js

@@ -32,7 +32,7 @@ import { createHash } from 'node:crypto';
 import { promisify } from 'node:util';
 
 import { StaysFixedError, messageOf } from '../core/errors.js';
-import { warn, detail } from '../core/log.js';
+import { warn, detail, shortPath } from '../core/log.js';
 import { findConfigFile, rootForConfig } from '../core/paths.js';
 import { sha256 } from '../core/hash.js';
 
@@ -326,20 +326,46 @@ 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} */
     const outcome = await settle(verdict, project.store, project.product, named);
+    // FIRST, before anything the run found. Which product was walked is the frame every
+    // other sentence here has to be read inside, and a person who was told it at the end
+    // has already read the clean result as being about the folder they are standing in.
+    if (project.elsewhere !== '') outcome.summary = `${project.elsewhere} ${outcome.summary}`;
     // Only a run that really did reach the surface it was aimed at may say so. The
     // confirmation is what lets a caller tell "it went there and found nothing" from
     // "it checked something else and found nothing", and those are not the same answer.
@@ -443,7 +469,14 @@ async function settle(verdict, store, product, guards) {
   verdict.findings = decided.reported;
   verdict.accounted = decided.accounting;
   if (verdict.blocked !== true) {
-    verdict.ok = decided.reported.length === 0 && (verdict.newlyUnstable ?? []).length === 0;
+    // `verdict.ok !== false` first, and it is the whole point of the line. Accounting may
+    // take a pass AWAY — a finding nobody waived, an address that stopped being
+    // predictable — and it may never hand one back. This assigned instead of narrowing, so
+    // every not-a-pass the engine had already decided was thrown away here: a run where the
+    // product never answered, and a run drowning in wobble, both came back through this line
+    // as `ok: true`. Found by the refusal lane on 2026-08-31, and it had been quietly
+    // discarding the wobble verdict before that.
+    verdict.ok = verdict.ok !== false && decided.reported.length === 0 && (verdict.newlyUnstable ?? []).length === 0;
     // The count goes into the sentence a person and an agent both read, not into a field
     // one of them has to know to look for.
     if (decided.accounting.waived > 0 || decided.accounting.expiredWaivers > 0) {
@@ -471,6 +504,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
@@ -620,7 +668,11 @@ export function whatWasNotChecked(coverage) {
   if (parts.length === 0) {
     return `Everything this run knows how to walk was walked — ${coverage.paths} ${coverage.paths === 1 ? 'address' : 'addresses'} across ${coverage.journeys} ${coverage.journeys === 1 ? 'journey' : 'journeys'}. That is not every possible state of your product; nothing can enumerate that, and a clean result only covers what was walked.`;
   }
-  return `NOT EVERYTHING WAS CHECKED: ${parts.join(', and ')}. A clean result only covers what was walked — the whole list is in coverage.gaps.`;
+  // `staysfixed coverage`, not `coverage.gaps`. This sentence is printed at a person as well
+  // as returned to an agent, and a person at a terminal has no JSON field to open — being
+  // told to read one is being told to go nowhere. The command is true for both readers, and
+  // the agent already had that wording on its own reply.
+  return `NOT EVERYTHING WAS CHECKED: ${parts.join(', and ')}. A clean result only covers what was walked — \`staysfixed coverage\` has the whole list.`;
 }
 
 /**
@@ -659,6 +711,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 +772,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.
  *
@@ -707,6 +917,13 @@ export async function sweepAbandonedScratch() {
   } catch {
     return;
   }
+  // Programs whose folder has ALREADY gone are swept first, because the loop below can never
+  // reach them: it walks folders, and theirs is not there any more. Fifteen `serve` processes
+  // were found in exactly that state on 2026-08-31, out of scratch folders deleted the day
+  // before. A folder that no longer exists is the strongest possible evidence that its run is
+  // over, so nothing that is still going is at risk here.
+  await stopRunsWhoseFolderHasGone();
+
   let taken = 0;
   for (const name of names) {
     if (taken >= MOST_PER_RUN) break;
@@ -726,11 +943,168 @@ export async function sweepAbandonedScratch() {
       }
     }
     if (!abandoned) continue;
+    // The folder is not the whole of what was left behind. Four `vite preview` servers from
+    // the day before were still running on this machine on 2026-08-31, out of scratch folders
+    // that had already been deleted — started by a run that died before it could stop them.
+    // Deleting the folder and leaving its programs running is a tool quietly consuming
+    // somebody's machine, and this one is going to be installed on machines that are not its
+    // author's. So the programs go first, and only then the folder.
+    await stopWhateverIsStillRunningIn(dir);
     await fsp.rm(dir, { recursive: true, force: true }).catch(() => {});
     taken += 1;
   }
 }
 
+/**
+ * Stop programs still running out of a scratch folder that has already been deleted.
+ *
+ * Every one of these was started by a check and outlived it. They hold ports and memory on a
+ * machine that is usually not this tool's author's, and nothing else on it has a
+ * `staysfixed-check-` path in its command line, so the match cannot catch a stranger.
+ *
+ * A folder that still exists is left completely alone here — a run that is going right now
+ * has its folder, and stopping its own servers would be this function breaking the check that
+ * called it.
+ *
+ * POSIX only, for the same reason as {@link stopWhateverIsStillRunningIn}: asking Windows
+ * this question needs a different command, and a wrong one there could stop something else.
+ *
+ * @returns {Promise<void>}
+ */
+async function stopRunsWhoseFolderHasGone() {
+  if (process.platform === 'win32') return;
+  /** @type {string} */
+  let listing = '';
+  try {
+    listing = (await exec('/bin/ps', ['-A', '-o', 'pid=,command='], { timeout: 10_000, maxBuffer: 8 * 1024 * 1024 })).stdout;
+  } catch {
+    return;
+  }
+  for (const line of listing.split('\n')) {
+    const folder = /(\S*staysfixed-check-[A-Za-z0-9]+)/.exec(line);
+    if (!folder) continue;
+    if (existsSync(folder[1])) continue;
+    const pid = Number.parseInt(line.trim().split(/\s+/)[0] ?? '', 10);
+    if (!Number.isFinite(pid) || pid <= 1 || pid === process.pid) continue;
+    for (const signal of /** @type {const} */ (['SIGTERM', 'SIGKILL'])) {
+      try {
+        process.kill(-pid, signal);
+      } catch {
+        try {
+          process.kill(pid, signal);
+        } catch {
+          // Gone already, or not ours to stop.
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Stop anything still running out of an abandoned scratch folder.
+ *
+ * Read from the process list rather than remembered, because the run that started these is
+ * gone — that is what made the folder abandoned. A program is only killed when the folder
+ * being reclaimed appears in its own command line, so nothing of anybody else's is touched.
+ *
+ * The whole group is signalled, not the one process: a server started through `npm run` is
+ * a shell that started Node, and killing the shell alone leaves the server holding its port.
+ *
+ * POSIX only. Windows needs a different question asked of the machine, and a wrong one there
+ * could kill something else, so it is left alone and said so rather than guessed at.
+ *
+ * @param {string} dir
+ * @returns {Promise<void>}
+ */
+async function stopWhateverIsStillRunningIn(dir) {
+  if (process.platform === 'win32') return;
+  /** @type {string} */
+  let listing = '';
+  try {
+    listing = (await exec('/bin/ps', ['-A', '-o', 'pid=,command='], { timeout: 10_000, maxBuffer: 8 * 1024 * 1024 })).stdout;
+  } catch {
+    return;
+  }
+  for (const line of listing.split('\n')) {
+    if (!line.includes(dir)) continue;
+    const pid = Number.parseInt(line.trim().split(/\s+/)[0] ?? '', 10);
+    if (!Number.isFinite(pid) || pid <= 1 || pid === process.pid) continue;
+    for (const signal of /** @type {const} */ (['SIGTERM', 'SIGKILL'])) {
+      try {
+        process.kill(-pid, signal);
+      } catch {
+        try {
+          process.kill(pid, signal);
+        } catch {
+          // Already gone, or somebody else's to stop. Either way there is nothing to do.
+        }
+      }
+    }
+  }
+}
+
+/**
+ * "There was nowhere to work", said the way every other refusal here is said.
+ *
+ * A check never runs anything against somebody's real folder: it copies the build into a
+ * throwaway folder inside the machine's temporary directory first. When that folder cannot
+ * be made, the run is over before it starts — and what a person was handed for it was the
+ * operating system's own words, `ENOENT: no such file or directory, mkdtemp
+ * '/nowhere/staysfixed-check-FHwIxx'`, pasted straight into the block this tool tells an
+ * agent to put in a summary for the person who owns the product. Measured 2026-08-31 with
+ * TMPDIR pointing at a folder that was not there, and again at one this user could not
+ * write to. Every other refusal in this file is a plain sentence; that one was a stack.
+ *
+ * The three that actually happen each get their own sentence, because the thing to DO about
+ * them is different every time: the folder is not there, the folder will not take writes, or
+ * the disk is full. Anything else keeps the machine's own words, framed as the machine's —
+ * when there is no sentence for it, the raw text is the only information there is, and
+ * dropping it would leave somebody with nothing at all.
+ *
+ * @param {unknown} e
+ * @returns {StaysFixedError}
+ */
+function noScratchFolder(e) {
+  const tmp = os.tmpdir();
+  const code = String(/** @type {any} */ (e)?.code ?? '');
+  // Worth naming only when a setting in this shell is what chose the folder. On a machine
+  // where nothing set it, saying "TMPDIR" sends somebody looking for a setting they have not
+  // got, and the folder is the operating system's own.
+  const yours = (process.env.TMPDIR ?? '').replace(/\/$/, '') === tmp.replace(/\/$/, '')
+    ? ' That folder is whatever TMPDIR is set to in this shell.'
+    : '';
+  /** @type {{why: string, hint: string}} */
+  const said =
+    code === 'ENOENT'
+      ? {
+        why: `There is no folder at ${tmp}, so there was nowhere to put it.`,
+        hint: `Make that folder, or point TMPDIR at one that exists — or unset TMPDIR to fall back to this machine's own — and run the check again.${yours}`,
+      }
+      : code === 'EACCES' || code === 'EPERM'
+        ? {
+          why: `${tmp} is there, but this user is not allowed to write in it.`,
+          hint: `Give yourself write access to that folder, or point TMPDIR at one you can write to, and run the check again.${yours}`,
+        }
+        : code === 'EROFS'
+          ? {
+            why: `${tmp} is on a disk that is mounted read-only, so nothing can be written there at all.`,
+            hint: `Point TMPDIR at a folder on a disk that takes writes and run the check again.${yours}`,
+          }
+          : code === 'ENOSPC'
+            ? {
+              why: `The disk holding ${tmp} is full.`,
+              hint: 'Free some space and run the check again. A check copies your project, so it needs about as much room as the project takes.',
+            }
+            : {
+              why: `${tmp} would not take it. The machine said: ${messageOf(e)}`,
+              hint: `Check that ${tmp} exists and that you can write in it, then run the check again.${yours}`,
+            };
+  return new StaysFixedError(
+    `Stays Fixed could not make the throwaway folder it works in, so nothing was opened, nothing was walked and nothing was compared. ${said.why}`,
+    { hint: said.hint, cause: e },
+  );
+}
+
 /**
  * Is that process still running? Signal 0 asks without sending anything.
  * @param {number} pid
@@ -766,8 +1140,20 @@ function plainly(what) {
  * @returns {CheckOutcome}
  */
 function blocked(options, e, storeTrouble) {
-  const product = options.product ?? path.basename(path.resolve(options.cwd ?? options.root ?? process.cwd()));
+  // The basename of the ROOT, not of the folder the command was typed in. Those are the
+  // same folder on almost every run, and on the one where they differ this record is
+  // written into the root's store — so naming it after the folder somebody happened to be
+  // standing in filed a run under a product that store has never heard of.
+  const root = projectRootFor(options);
+  const product = options.product ?? path.basename(root);
   const empty = { id: '', product };
+  // Which folder this is about, said before the reason it could not be done. A blocked run
+  // inside a sub-project is the easiest of all to misread: nothing was walked, so there is
+  // nothing in the answer to give away that it was never about this folder in the first
+  // place. `options.product` is passed rather than the name worked out above, because a name
+  // taken from a folder is not a product name and quoting it as one would put a product in
+  // front of somebody that nothing anywhere calls that.
+  const elsewhere = aboutSomewhereElse({ from: startedIn(options), root, product: options.product })?.note ?? '';
   return {
     runId: new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14),
     product,
@@ -790,7 +1176,7 @@ function blocked(options, e, storeTrouble) {
     // The hint is the half that tells a person what to DO about it, and dropping it
     // turns a helpful error into a dead end. Anything that blocks a run has to carry
     // both halves all the way out to whoever reads the summary.
-    summary: `The check could not be run, so this is not a pass and not a failure. ${storeTrouble ? `${storeTrouble} ` : ''}${messageOf(e)}${
+    summary: `${elsewhere ? `${elsewhere} ` : ''}The check could not be run, so this is not a pass and not a failure. ${storeTrouble ? `${storeTrouble} ` : ''}${messageOf(e)}${
       e instanceof Error && /** @type {any} */ (e).hint ? ` ${/** @type {any} */ (e).hint}` : ''
     }`,
     durationMs: 0,
@@ -1198,6 +1584,10 @@ async function waitForItsWindow(pid, stopped) {
  * @property {string} storeTrouble  Empty on a normal run. A plain sentence when the store
  *   would not take this run's records — the run went ahead anyway, and every answer it
  *   produces has to carry the admission that nothing about it was kept.
+ * @property {string} elsewhere  Empty when the check is about the folder it was typed in.
+ *   Otherwise the sentence naming which product this run is really about and where it is,
+ *   which goes on the FRONT of the answer so nobody reads a clean result as being about a
+ *   folder that was never walked.
  * @property {import('./run.js').Walker} walk
  * @property {(reference: BuildFingerprint, ctx: {events?: CheckEvents, signal?: AbortSignal}) => Promise<LiveBuild|null>} bootReference
  * @property {(capture: Capture) => Capture} normalise
@@ -1214,11 +1604,98 @@ async function waitForItsWindow(pid, stopped) {
  * @returns {string}
  */
 function projectRootFor(options) {
-  const from = path.resolve(options.cwd ?? options.root ?? process.cwd());
+  const from = startedIn(options);
   const config = options.configFile ?? findConfigFile(from);
   return config ? rootForConfig(config) : from;
 }
 
+/**
+ * The folder the command was actually typed in.
+ *
+ * @param {CheckOptions} options
+ * @returns {string}
+ */
+function startedIn(options) {
+  return path.resolve(options.cwd ?? options.root ?? process.cwd());
+}
+
+/**
+ * Files that mean "this folder is a project in its own right".
+ *
+ * Any one of them is enough. They are the files a person points at when asked "where does
+ * this thing live", and every one of them is what a package manager or a language's own
+ * tooling reads as the top of a project.
+ */
+const A_PROJECT_OF_ITS_OWN = [
+  'package.json', '.git', 'go.mod', 'Cargo.toml', 'pyproject.toml', 'pom.xml',
+  'build.gradle', 'build.gradle.kts', 'Gemfile', 'composer.json', 'deno.json',
+];
+
+/**
+ * When a check is not about the folder somebody is standing in, say so.
+ *
+ * Settings are found by walking UP from where the command was typed, which is right: a
+ * check run from `src/` is meant to be about the project `src/` is part of. But the same
+ * walk reaches out of a project and into the one above it. Stand in a sub-folder that is
+ * its own git repository with its own package.json, run a check, and the run quietly
+ * measures the PARENT'S product and comes back clean — measured 2026-08-31, where a folder
+ * holding `child-product` was reported on as `parent-product` with nothing said about the
+ * swap. Somebody reading that has been handed a clean result about a product they were not
+ * asking about, which is the exact failure this tool exists to prevent.
+ *
+ * So every run that is about somewhere else says which product it is about and where that
+ * product is, and a run that stepped out of a project of its own says it loudly and says
+ * what to do instead. Nothing is refused: reaching up is usually right, and being told what
+ * happened is what makes it safe.
+ *
+ * Exported so a test can ask the question without running a whole check.
+ *
+ * @param {{from: string, root: string, product?: string}} where
+ * @returns {{note: string, gap: CoverageGap|null}|null}  Null when the check really is
+ *   about the folder it was typed in, which is the ordinary case.
+ */
+export function aboutSomewhereElse(where) {
+  const from = path.resolve(where.from);
+  const root = path.resolve(where.root);
+  if (from === root) return null;
+  const named = where.product ? `"${where.product}"` : path.basename(root);
+
+  const itsOwn = A_PROJECT_OF_ITS_OWN.filter((name) => existsSync(path.join(from, name)));
+  if (itsOwn.length === 0) {
+    // Ordinary and usually wanted: somebody is standing inside the project they meant. One
+    // sentence, so a clean answer still carries the name of what it is a clean answer about.
+    return {
+      note: `This check was aimed at ${named}, the project at ${shortPath(root)}; you ran it from ${shortPath(from)}, which is inside it.`,
+      gap: null,
+    };
+  }
+
+  const because = itsOwn.includes('.git') && itsOwn.length > 1
+    ? `it is its own git repository and has its own ${itsOwn.filter((n) => n !== '.git').join(' and ')}`
+    : itsOwn.includes('.git')
+      ? 'it is its own git repository'
+      : `it has its own ${itsOwn.join(' and ')}`;
+  // "was aimed at", not "walked": this same sentence goes on the front of a blocked run,
+  // where nothing was walked at all, and a frame that claims more than happened would be
+  // the same kind of lie in miniature as the one it is here to stop.
+  const note =
+    `NOT THE FOLDER YOU ARE STANDING IN. This check was aimed at ${named}, the project at ${shortPath(root)} — ` +
+    `not at ${shortPath(from)}, which is where you ran it. That folder is a project in its own right (${because}) ` +
+    `and it has no Stays Fixed settings of its own, so the settings from the folder above it are what this run used. ` +
+    `Nothing inside ${shortPath(from)} was checked, so nothing below says anything about it. ` +
+    `Run \`staysfixed init\` there to check that project on its own.`;
+  return {
+    note,
+    gap: {
+      what: `Everything in ${shortPath(from)}, the folder this check was run from.`,
+      why:
+        `It is a project in its own right (${because}), and it has no Stays Fixed settings of its own. ` +
+        `Settings are found by walking up, so the ones at ${shortPath(root)} were used and ${named} was walked instead.`,
+      unlockedBy: `Run \`staysfixed init\` in ${shortPath(from)} to give that project its own settings, and check it from there.`,
+    },
+  };
+}
+
 /**
  * How many builds keep their whole record before the old ones are thinned out.
  *
@@ -1500,9 +1977,17 @@ async function openProject(options) {
   }
 
   await sweepAbandonedScratch();
-  const scratch = await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-check-'));
-  const evidenceDir = path.join(scratch, 'evidence');
-  await fsp.mkdir(evidenceDir, { recursive: true });
+  /** @type {string} */
+  let scratch;
+  /** @type {string} */
+  let evidenceDir;
+  try {
+    scratch = await fsp.mkdtemp(path.join(os.tmpdir(), 'staysfixed-check-'));
+    evidenceDir = path.join(scratch, 'evidence');
+    await fsp.mkdir(evidenceDir, { recursive: true });
+  } catch (e) {
+    throw noScratchFolder(e);
+  }
   // Who this belongs to, so a later run can tell an abandoned copy from one in use.
   await fsp.writeFile(path.join(scratch, 'owner.json'), JSON.stringify({ pid: process.pid, at: new Date().toISOString() })).catch(() => {});
 
@@ -1591,6 +2076,14 @@ 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.`,
     });
   }
+  // Which folder this answer is about, when it is not the one the command was typed in.
+  // It goes in the coverage list as well as on the front of the summary because the list is
+  // what a build server's table and the closing count both read, and a fact that lives on
+  // one field somebody has to know to look for is a fact most readers never meet.
+  const elsewhere = aboutSomewhereElse({ from: startedIn(options), root, product });
+  if (elsewhere?.gap) gaps.push(elsewhere.gap);
+  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.',
@@ -1633,6 +2126,7 @@ async function openProject(options) {
     journeys,
     gaps,
     storeTrouble: storeTrouble.join(' '),
+    elsewhere: elsewhere?.note ?? '',
     walk,
     bootReference,
     normalise,
@@ -2227,6 +2721,19 @@ function nameOfReference(reference, asked) {
 async function exportBuild(root, reference, scratch) {
   const sha = reference.gitSha;
   if (!sha) return null;
+  // A reference cut from a tree with uncommitted changes is filed under a fingerprint of
+  // that TREE — an id like `work-76ac0155c8b9`, deliberately not the commit's — because the
+  // files that were checked are not the files git has. Exporting the commit and calling it
+  // "the old build" walked different code, and everything downstream believed it: an address
+  // the record holds a real value for was walked against a build that never had it, the
+  // silence was read as proof the address is new, and the reply said "is there now and was
+  // not before" about a value sitting in the record on disk. Measured 2026-08-31.
+  //
+  // Falling back to the stored record is weaker, and the run says so. That is the same choice
+  // this tool already makes everywhere the old build cannot be walked, and it is the honest
+  // one: a weaker comparison you are told about beats a strong-looking comparison against
+  // the wrong build.
+  if (reference.dirty === true) return null;
   const dir = path.join(scratch, `reference-${sha.slice(0, 12)}`);
   await fsp.mkdir(dir, { recursive: true });
   try {