staysfixed 0.9.1 → 0.11.0

package/src/v2/mcp/tools.js

@@ -32,6 +32,7 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { isExpected, messageOf } from '../../core/errors.js';
 import { findConfigFile, rootForConfig } from '../../core/paths.js';
@@ -75,16 +76,114 @@ import {
 /**
  * What every tool call is handed.
  *
+ * `audience` is who is on the other end of this particular call. It is NOT a second set of
+ * answers - see THE TWO AUDIENCES below - and nothing in this file is allowed to decide a
+ * fact by it.
+ *
  * @typedef {object} ToolContext
  * @property {string} root
  * @property {string} cwd
  * @property {string} version
  * @property {string} protocolVersion
+ * @property {'agent'|'person'} [audience]  Who asked. Defaults to an agent: over MCP is what
+ *                                          this file is for, and only the command line, which
+ *                                          calls these functions directly, says otherwise.
  */
 
 /** @typedef {{type: 'text', text: string}|{type: 'image', data: string, mimeType: string}} ContentItem */
 /** @typedef {{content: ContentItem[], structuredContent?: Record<string, unknown>, isError?: boolean}} ToolResult */
 
+// ---------------------------------------------------------------------------
+// THE TWO AUDIENCES
+// ---------------------------------------------------------------------------
+
+/**
+ * The same truth, in the words the reader can act on.
+ *
+ * Every tool here assembles its answer exactly once, and that must never change: a person
+ * and an agent told different things about the same product is the precise bug this whole
+ * tool exists to catch, and shipping it inside the tool itself would be a poor joke. What
+ * genuinely differs is the handful of sentences naming a NEXT STEP, because the two readers
+ * cannot take the same one. An agent calls `staysfixed_check`. A person types
+ * `staysfixed check` and has no MCP tool at all.
+ *
+ * Measured 2026-08-31, after `coverage`, `explain`, `prove`, `waive` and `intent` were given
+ * commands of their own: `staysfixed intent "..." --touches src/total.js` printed, as its
+ * closing line, "Now run staysfixed_check." - the name of a tool the reader does not have,
+ * cannot type, and will not find in `staysfixed --help`. `explain` offered `include:
+ * ["evidence"]`, `prove` asked for `{ "revert": ["..."] }`, and `coverage` sent a person to
+ * `staysfixed_capabilities`. Four commands, each ending in an instruction addressed to
+ * somebody else.
+ *
+ * So: facts are written once, and any sentence naming a step asks this phrasebook for the
+ * words. Nothing in here may change what is true - only how it is reached. The one field
+ * that is not wording is `by`, and it is here for the same reason: it records which of these
+ * two actually made the call, and it has to agree with everything else in the reply.
+ *
+ * @typedef {object} Voice
+ * @property {'agent'|'person'} who
+ * @property {boolean} isPerson
+ * @property {string} by            What goes on the record as who did this.
+ * @property {string} check         How this reader runs a check.
+ * @property {string} capabilities  How this reader asks what the machine can do.
+ * @property {string} explainCall   A whole example call to explain one finding.
+ * @property {string} proveCall     A whole example call to prove a cause.
+ * @property {string} revertArg     Just the "what to put back" part of that call.
+ * @property {string} waiveCall     A whole example call to record one as intended.
+ * @property {string} askForEvidence
+ * @property {string} askForMachines
+ * @property {string} budgetEnds   What happens when the five run out, said to this reader.
+ */
+
+/** @type {Record<'agent'|'person', Voice>} */
+const VOICES = {
+  agent: {
+    who: 'agent',
+    isPerson: false,
+    by: 'an agent, over MCP',
+    check: 'staysfixed_check',
+    capabilities: 'staysfixed_capabilities',
+    explainCall: '{ "finding": "f-a1b2c3" }',
+    proveCall: '{ "finding": "f-a1b2c3", "revert": ["src/checkout/total.js"] }',
+    revertArg: '{ "revert": ["src/checkout/total.js"] }',
+    waiveCall: '{ "finding": "f-a1b2c3", "because": "..." }',
+    askForEvidence: 'Ask with include: ["evidence"].',
+    askForMachines: 'A person can run `staysfixed doctor --machines` to ask',
+    budgetEnds: 'before a person has to look',
+  },
+  person: {
+    who: 'person',
+    isPerson: true,
+    by: 'a person, at the command line',
+    check: 'staysfixed check',
+    capabilities: 'staysfixed doctor',
+    explainCall: 'staysfixed explain f-a1b2c3',
+    proveCall: 'staysfixed prove f-a1b2c3 --revert src/checkout/total.js',
+    revertArg: '--revert src/checkout/total.js',
+    waiveCall: 'staysfixed waive f-a1b2c3 --because "..."',
+    askForEvidence: 'Add --evidence to see it.',
+    askForMachines: 'Run `staysfixed doctor --machines` to ask',
+    // "before a person has to look" is the agent's version of this, and read by the person
+    // themselves it says nothing at all - they ARE the person, sitting right there.
+    budgetEnds: 'before this refuses and the rest have to be fixed rather than recorded',
+  },
+};
+
+/**
+ * Which of the two asked.
+ *
+ * Anything that did not say is a program: over MCP is what this file is for, and the only
+ * caller that is not speaking MCP is `askTheToolSet` in src/v2/cli.js, which says so.
+ * Defaulting the other way would put "a person, at the command line" on records sealed by
+ * an agent, which is the same untrue record in the opposite direction.
+ *
+ * @param {ToolContext} ctx
+ * @returns {Voice}
+ */
+export function voiceFor(ctx) {
+  return ctx?.audience === 'person' ? VOICES.person : VOICES.agent;
+}
+
 // ---------------------------------------------------------------------------
 // Constants that are policy, not preference
 // ---------------------------------------------------------------------------
@@ -210,16 +309,21 @@ export async function loadEngine(refresh = false) {
 }
 
 /**
- * What an agent gets when it asks for something only the engine can do and the
+ * What a caller gets when it asks for something only the engine can do and the
  * engine is not there. Written as instructions to whoever is integrating,
  * because that is the only person who will ever read it.
  *
+ * The last line names a next step, so it is the one line that has to know who is reading:
+ * `staysfixed_capabilities` is a tool a person at a terminal does not have, and `staysfixed
+ * doctor` is the same question asked in the words they can type.
+ *
  * @param {Engine} engine
  * @param {string} part
  * @param {string} needs   The exact signature the missing function must have.
+ * @param {Voice} voice
  * @returns {ToolResult}
  */
-function engineMissing(engine, part, needs) {
+function engineMissing(engine, part, needs, voice) {
   const names = (/** @type {Record<string, string[]>} */ (ENGINE_PARTS)[part] ?? []).join(' or ');
   return problem(
     [
@@ -230,7 +334,7 @@ function engineMissing(engine, part, needs) {
       '',
       `It needs: ${needs}`,
       '',
-      'Everything else still works. Call staysfixed_capabilities for what this copy can do.',
+      `Everything else still works. ${voice.isPerson ? 'Run' : 'Call'} ${voice.capabilities} for what this copy can do.`,
     ].join('\n')
   );
 }
@@ -362,7 +466,8 @@ export function toolDefinitions() {
           touches: {
             type: 'array',
             items: { type: 'string' },
-            description: 'Files, folders or named areas you expect this to affect, e.g. ["src/checkout/total.js", "the basket page"]. A difference outside this list cannot be waived.',
+            description:
+              'Files, folders or named areas you expect this to affect, e.g. ["src/checkout/total.js", "the basket page"]. A difference outside this list cannot be waived. Paths may be relative to the project or absolute - an absolute path inside the project is stored relative to it, and the reply says exactly what was sealed.',
           },
           expect: { type: 'array', items: { type: 'string' }, description: 'Differences you expect this change to produce, in your own words. Optional, and it makes the check sharper.' },
         },
@@ -468,7 +573,10 @@ export function toolDefinitions() {
         'What was NOT checked. The ways in that no journey has ever opened, the surfaces this machine cannot reach at all, anything refused because doing it twice would not have been reversible, and the things this tool can never see on any machine. Read it before you tell anyone a change is safe: a clean check only covers what was walked, and this is the list of what was not.',
       inputSchema: {
         type: 'object',
-        properties: { format: { type: 'string', enum: ['text', 'json'] } },
+        properties: {
+          format: { type: 'string', enum: ['text', 'json'] },
+          offline: { type: 'boolean', description: 'Do not look for any other machine at all. Faster, and then this answer cannot say anything about remote runners either way.' },
+        },
         additionalProperties: false,
       },
     },
@@ -684,6 +792,67 @@ const RESULT_SHAPES = [
 // intent
 // ---------------------------------------------------------------------------
 
+/**
+ * The name of a file, said the way the rest of the tool says it.
+ *
+ * An agent holds ABSOLUTE paths. That is what its own editing tools hand it and that is
+ * what it types back here, so `touches` arrives as `/Users/…/tiny/cli.js` while every
+ * address, every source file and every intent comparison downstream is written relative to
+ * the project. Nothing lines those two up, and the gate that decides whether a difference
+ * was declared fell straight through to "one word in common is not a match".
+ *
+ * Measured on a product with ONE file in it: seal `/var/…/tiny/cli.js`, edit that same
+ * file, run a check, and `staysfixed_waive` answered "Refused. This is outside what you
+ * sealed… Only the word 'cli' lines up." The one file in the product, the file the agent
+ * had just edited, reported as something it never said it was touching. Naming the same
+ * file `cli.js` was accepted. So the two spellings meant opposite things, and the one an
+ * agent naturally reaches for was the broken one.
+ *
+ * Only a real path that really sits inside this project is rewritten. Everything else is
+ * passed through exactly as written, because `touches` also takes plain areas — "the
+ * basket page" — and mangling those would break the match it is there to make.
+ *
+ * @param {string} named   What the agent called it.
+ * @param {string} root    The project root.
+ * @returns {string}
+ */
+function insideTheProject(named, root) {
+  let where = named;
+  if (where.startsWith('file://')) {
+    try {
+      where = fileURLToPath(where);
+    } catch {
+      return named;
+    }
+  }
+  if (!path.isAbsolute(where)) return named;
+
+  /**
+   * @param {string} from
+   * @param {string} to
+   * @returns {string|null}
+   */
+  const under = (from, to) => {
+    const rel = path.relative(from, to);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : null;
+  };
+
+  const plain = under(root, where);
+  if (plain) return plain;
+
+  // The same folder under two names. On a Mac `/tmp` is a link to `/private/tmp`, so the
+  // path an agent reports and the root this tool worked out can be the identical folder
+  // spelled two ways, and comparing the text alone says they are unrelated.
+  try {
+    const real = under(fs.realpathSync(root), fs.realpathSync(where));
+    if (real) return real;
+  } catch {
+    // A path that does not exist cannot be resolved, and that is not an error here: an
+    // agent may name a file it is about to create. Its own words stand.
+  }
+  return named;
+}
+
 /**
  * @param {ToolContext} ctx
  * @param {Record<string, any>} input
@@ -691,7 +860,7 @@ const RESULT_SHAPES = [
  */
 async function toolIntent(ctx, input) {
   const summary = text(input.summary);
-  const touches = stringList(input.touches) ?? [];
+  const touches = (stringList(input.touches) ?? []).map((t) => insideTheProject(t, ctx.root));
   const expect = stringList(input.expect) ?? [];
 
   if (!summary) return problem('Say what you meant to change, in one plain sentence: { "summary": "...", "touches": ["..."] }.');
@@ -703,11 +872,20 @@ async function toolIntent(ctx, input) {
 
   const store = storeFor(ctx);
   const product = await productFor(ctx.root);
+  const voice = voiceFor(ctx);
 
   // src/v2/intent.js does the sealing, and it does more than write a file down: it
   // fingerprints the working tree at this moment, so whether the intent was written before
   // the edits or after them stops being a promise and becomes something anybody can check.
-  const intent = await sealIntent(store, { product, summary, touches, expect, by: 'an agent, over MCP' });
+  //
+  // WHO SEALED IT IS PART OF THE EVIDENCE. `by` used to be the constant string 'an agent,
+  // over MCP' whoever called, so from the day `staysfixed intent` became a command every
+  // intent a person sealed at their own terminal went on the record as an agent's - measured
+  // 2026-08-31, the first CLI run wrote exactly that into
+  // .staysfixed/v2/intents/<product>.json. This record is what a waiver is judged against
+  // months later, by somebody deciding whether a claim of "I meant that" is worth anything,
+  // and a record naming the wrong actor is a record nobody can use.
+  const intent = await sealIntent(store, { product, summary, touches, expect, by: voice.by });
 
   // Sealing a new intent does NOT hand out a fresh five. The budget is counted
   // against the reference, precisely so an agent that has spent its waivers
@@ -726,8 +904,8 @@ async function toolIntent(ctx, input) {
           expect.length ? `Expecting to see: ${expect.join('; ')}.` : '',
           intent.ordering,
           '',
-          `You may waive at most ${WAIVER_BUDGET} differences before a person has to look, and ${spent} of those are already spent since the last time a build shipped. Sealing another intent does not give you more, and you can only waive a difference that falls inside what you just named.`,
-          'Now run staysfixed_check.',
+          `You may waive at most ${WAIVER_BUDGET} differences ${voice.budgetEnds}, and ${spent} of those are already spent since the last time a build shipped. Sealing another intent does not give you more, and you can only waive a difference that falls inside what you just named.`,
+          `Now run ${voice.check}.`,
         ]
           .filter(Boolean)
           .join('\n'),
@@ -749,7 +927,7 @@ async function toolCheck(ctx, input) {
   const engine = await loadEngine();
   const run = engine.parts.check;
   if (!run) {
-    return engineMissing(engine, 'check', 'check({cwd, configFile, against, paired, journeys, only}) returning a CheckResult - the shape at the top of src/v2/cli.js.');
+    return engineMissing(engine, 'check', 'check({cwd, configFile, against, paired, journeys, only}) returning a CheckResult - the shape at the top of src/v2/cli.js.', voiceFor(ctx));
   }
 
   const store = storeFor(ctx);
@@ -1257,11 +1435,12 @@ function renderFinding(f) {
  * @returns {Promise<ToolResult>}
  */
 async function toolExplain(ctx, input) {
+  const voice = voiceFor(ctx);
   const id = text(input.finding);
-  if (!id) return problem('Say which finding to explain, e.g. { "finding": "f-a1b2c3" }. The ids come from staysfixed_check.');
+  if (!id) return problem(`Say which finding to explain, e.g. ${voice.explainCall}. The ids come from ${voice.check}.`);
 
   const last = await readCheckRecord(storeFor(ctx));
-  if (!last) return problem('No check has run in this copy yet, so there is nothing to explain. Run staysfixed_check first.');
+  if (!last) return problem(`No check has run in this copy yet, so there is nothing to explain. Run ${voice.check} first.`);
   const f = last.findings.find((x) => x.id === id);
   if (!f) {
     const ids = last.findings.slice(0, 12).map((x) => x.id);
@@ -1331,7 +1510,7 @@ async function toolExplain(ctx, input) {
     }
   } else if (f.evidence) {
     out.push('');
-    out.push('Evidence was kept and not sent. Ask with include: ["evidence"].');
+    out.push(`Evidence was kept and not shown. ${voice.askForEvidence}`);
   }
 
   if (deep?.error) {
@@ -1354,7 +1533,15 @@ async function toolExplain(ctx, input) {
       content.push({ type: 'image', data: png.toString('base64'), mimeType: 'image/png' });
     }
   } else if (pictures.length) {
-    content.push({ type: 'text', text: `${pictures.length} picture(s) were kept as evidence and not sent. Ask with include: ["pixels"] if a picture would settle it.` });
+    // A terminal cannot be handed a PNG, so "ask with include: [\"pixels\"]" is not an
+    // instruction a person can carry out - and telling them a picture exists without saying
+    // WHERE leaves them worse off than saying nothing. They get the paths and open them.
+    content.push({
+      type: 'text',
+      text: voice.isPerson
+        ? `${pictures.length} picture(s) were kept as evidence: ${pictures.slice(0, MAX_IMAGES).join(', ')}${pictures.length > MAX_IMAGES ? `, and ${pictures.length - MAX_IMAGES} more` : ''}. Open them if a picture would settle it.`
+        : `${pictures.length} picture(s) were kept as evidence and not sent. Ask with include: ["pixels"] if a picture would settle it.`,
+    });
   }
 
   return { content };
@@ -1383,24 +1570,26 @@ function picturesFrom(f, deep) {
  * @returns {Promise<ToolResult>}
  */
 async function toolProve(ctx, input) {
+  const voice = voiceFor(ctx);
   const engine = await loadEngine();
   const run = engine.parts.prove;
   if (!run) {
     return engineMissing(
       engine,
       'prove',
-      'prove({cwd, configFile, finding, revert}) returning {gone: boolean, detail?: string}. src/v2/cause.js already has proveCause(), but it takes an engine-internal finding and a loaded project, which this surface does not have - a small facade in src/v2/check.js is all that is needed.'
+      'prove({cwd, configFile, finding, revert}) returning {gone: boolean, detail?: string}. src/v2/cause.js already has proveCause(), but it takes an engine-internal finding and a loaded project, which this surface does not have - a small facade in src/v2/check.js is all that is needed.',
+      voice
     );
   }
 
   const id = text(input.finding);
   const revert = stringList(input.revert);
-  if (!id) return problem('Say which finding you are trying to explain, e.g. { "finding": "f-a1b2c3", "revert": ["src/total.js"] }.');
-  if (!revert) return problem('Name what to put back to the reference for one run, e.g. { "revert": ["src/checkout/total.js"] }. Without that there is no claim to test.');
+  if (!id) return problem(`Say which finding you are trying to explain, e.g. ${voice.proveCall}.`);
+  if (!revert) return problem(`Name what to put back to the reference for one run, e.g. ${voice.revertArg}. Without that there is no claim to test.`);
 
   const last = await readCheckRecord(storeFor(ctx));
   const f = last?.findings.find((x) => x.id === id);
-  if (!f) return problem(`The last check has no finding called "${id}". Run staysfixed_check first, then prove one of the ids it gives you.`);
+  if (!f) return problem(`The last check has no finding called "${id}". Run ${voice.check} first, then prove one of the ids it gives you.`);
 
   /** @type {any} */
   const result = (await run({ cwd: ctx.root, finding: id, revert })) ?? {};
@@ -1441,14 +1630,15 @@ async function toolProve(ctx, input) {
  * @returns {Promise<ToolResult>}
  */
 async function toolWaive(ctx, input) {
+  const voice = voiceFor(ctx);
   const id = text(input.finding);
   const because = text(input.because);
-  if (!id) return problem('Say which finding, e.g. { "finding": "f-a1b2c3", "because": "..." }.');
+  if (!id) return problem(`Say which finding, e.g. ${voice.waiveCall}.`);
   if (!because) return problem('Say why this difference is what you meant, in one plain sentence. A waiver with no reason is worth nothing to whoever reads it later.');
 
   const store = storeFor(ctx);
   const last = await readCheckRecord(store);
-  if (!last) return problem('No check has run in this copy yet, so there is no difference to waive. Run staysfixed_check first.');
+  if (!last) return problem(`No check has run in this copy yet, so there is no difference to waive. Run ${voice.check} first.`);
   const f = last.findings.find((x) => x.id === id);
   if (!f) return problem(`The last check has no finding called "${id}". You can only waive something this tool actually reported.`);
 
@@ -1464,7 +1654,13 @@ async function toolWaive(ctx, input) {
     finding: f,
     why: because,
     check: { at: last.at, runId: last.result?.runId },
-    by: 'an agent, over MCP',
+    // Same reason as the intent above: from the day `staysfixed waive` became a command,
+    // a constant here would have put an agent's name on every waiver a person recorded at
+    // their own terminal, and a waiver is read months later by somebody weighing exactly
+    // that. `audience` rides along so the sealed-class refusal is worded at whoever is
+    // actually reading it - see sayRefusal in src/v2/sealed.js.
+    by: voice.by,
+    audience: voice.who,
   });
 
   // A refusal is the tool working, not the tool being difficult, and the wording is the
@@ -1496,11 +1692,22 @@ async function toolWaive(ctx, input) {
  * here at all. A report missing either half would let somebody read "everything
  * walked" and believe the product was covered when the phone was never touched.
  *
+ * THE SURVEY IS THE ONE THE PERSON GETS. This call used to ask for it with `offline: true`
+ * written into the code, and then print the answer under the words "Cannot be reached from
+ * this machine at all". Offline means the ssh config is not even READ, so on a Mac with two
+ * machines named in it the agent was told, flatly, "No Windows desktop is reachable from
+ * here", while `staysfixed doctor` on the same Mac names both and says nothing is known
+ * about them either way. Forcing the answer and then reporting the forced answer as a fact
+ * about the world is the exact failure this tool exists to catch, so the question is now
+ * asked the same way `staysfixed_capabilities` and `doctor` ask it, and a caller who wants
+ * no network at all says so.
+ *
  * @param {ToolContext} ctx
  * @param {Record<string, any>} input
  * @returns {Promise<ToolResult>}
  */
 async function toolCoverage(ctx, input) {
+  const voice = voiceFor(ctx);
   const engine = await loadEngine();
   const last = await readCheckRecord(storeFor(ctx));
 
@@ -1508,7 +1715,7 @@ async function toolCoverage(ctx, input) {
   let caps = null;
   if (engine.parts.capabilities) {
     try {
-      caps = await engine.parts.capabilities({ cwd: ctx.root, offline: true });
+      caps = await engine.parts.capabilities({ cwd: ctx.root, offline: input.offline === true });
     } catch {
       // The machine survey is one half of the answer, not the whole of it. Losing
       // it must not lose the half that came from the run.
@@ -1517,12 +1724,40 @@ async function toolCoverage(ctx, input) {
   }
 
   const coverage = last?.result?.coverage ?? null;
-  const unreachable = (caps?.surfaces ?? []).filter((/** @type {any} */ s) => s.status === 'unavailable');
+  const unavailable = (caps?.surfaces ?? []).filter((/** @type {any} */ s) => s.status === 'unavailable');
+  // Two completely different sentences were being printed under one heading. "There is no
+  // Android app in this repository" is not "this machine cannot reach an Android device" —
+  // the first is nothing to check, the second is a hole in the coverage — and `doctor`
+  // already tells a person those apart in so many words. The agent was told both were the
+  // machine's fault, which reads as a crippled install rather than a project that simply
+  // has no phone app in it.
+  const nothingOfThatKind = unavailable.filter((/** @type {any} */ s) => s.notInThisProject === true);
+  const unreachable = unavailable.filter((/** @type {any} */ s) => s.notInThisProject !== true);
   const partial = (caps?.surfaces ?? []).filter((/** @type {any} */ s) => s.status === 'partial');
+  // Machines the survey NAMED and never asked. Nothing above rests on having asked them,
+  // and saying so is the difference between "there is no Windows desktop" and "nobody
+  // knocked". The command that knocks belongs to a person, not to an agent: dialling
+  // somebody's ssh config is what `doctor` deliberately stopped doing unasked.
+  const notDialled = (caps?.hosts ?? []).filter((/** @type {any} */ h) => h.reachable !== true && /not dialled/i.test(String(h.how ?? '')));
+  // And the other way the machine list can come back empty: somebody asked for no network
+  // at all, here or in STAYSFIXED_OFFLINE, and then the ssh config is not even read. An
+  // empty list looks identical to "there are no other machines", so which of the two it is
+  // has to be said. That is the whole defect this call had: force the answer, then report
+  // the forced answer as a finding about the world.
+  const lookedForNoMachines = input.offline === true || process.env.STAYSFIXED_OFFLINE !== undefined;
 
   if (input.format === 'json') {
     const payload = {
       lastCheckAt: last?.at ?? null,
+      // A cold start has no numbers to give, and nulls beside an empty `unopened` list read
+      // like a product with no holes in it. This says which of the two it is in one field.
+      anyCheckHasRun: last !== null,
+      note:
+        last === null
+          ? 'No check has run in this copy yet, so nothing at all has been covered and every count below is empty because nothing was measured, not because nothing was missed.'
+          : coverage
+            ? null
+            : 'The last run did not report what it covered, so how deep it went is unknown. Treat its clean result with suspicion.',
       covers: caps?.covers ?? null,
       walked: coverage?.journeys ?? null,
       doorsKnown: coverage?.doorsKnown ?? null,
@@ -1540,6 +1775,15 @@ async function toolCoverage(ctx, input) {
         .filter((/** @type {{doors?: number}} */ g) => typeof g.doors !== 'number')
         .map((/** @type {{what: string, why?: string, unlockedBy?: string}} */ g) => ({ what: g.what, why: g.why ?? null, unlockedBy: g.unlockedBy ?? null })),
       surfacesOutOfReach: unreachable.map((/** @type {any} */ s) => ({ name: s.name, why: s.summary, needs: s.needs })),
+      // Kept apart from `surfacesOutOfReach` on purpose: nothing of this kind exists in the
+      // project, so there is nothing here to check and it is not a limit of the machine.
+      surfacesNotInThisProject: nothingOfThatKind.map((/** @type {any} */ s) => ({ name: s.name, why: s.summary })),
+      // Named in the ssh config, never asked. Whatever is in `surfacesOutOfReach` above,
+      // none of it rests on having knocked on these.
+      machinesNotDialled: notDialled.map((/** @type {any} */ h) => ({ name: h.name, why: h.how })),
+      // True when this answer was taken without looking for other machines at all, so
+      // `machinesNotDialled` being empty means nobody looked, not that there are none.
+      machinesNotLookedFor: lookedForNoMachines,
       surfacesPartial: partial.map((/** @type {any} */ s) => ({ name: s.name, why: s.summary })),
       neverVisible: caps?.limits ?? null,
     };
@@ -1604,6 +1848,12 @@ async function toolCoverage(ctx, input) {
     for (const d of noAdapter) out.push(`- ${d.surface}: ${d.why}`);
   }
 
+  if (nothingOfThatKind.length) {
+    out.push('');
+    out.push('There is nothing of these kinds in this project, so there was nothing here to check and this is not a limit of the machine:');
+    for (const s of nothingOfThatKind) out.push(`- ${s.name}: ${s.summary}`);
+  }
+
   if (unreachable.length) {
     out.push('');
     out.push('Cannot be reached from this machine at all, so nothing there has been checked by anything:');
@@ -1612,9 +1862,26 @@ async function toolCoverage(ctx, input) {
       for (const need of s.needs ?? []) out.push(`    it would take: ${need.fix ?? need.what}`);
     }
   }
+
+  // Said even when nothing above needed a second machine. A machine quietly left out of
+  // this answer is a runner somebody may be looking for, and "no Windows desktop is
+  // reachable from here" printed over an ssh config naming two of them is not a finding
+  // about the world — it is a question nobody asked.
+  if (lookedForNoMachines) {
+    out.push('');
+    out.push(
+      'This answer was taken without looking for any other machine, so nothing above is a statement about what this machine can reach. Ask again without offline to find out.'
+    );
+  } else if (notDialled.length) {
+    out.push('');
+    out.push(
+      `${notDialled.length} ${notDialled.length === 1 ? 'machine is named in your ssh config and was' : 'machines are named in your ssh config and were'} not dialled, so nothing above rests on having asked ${notDialled.length === 1 ? 'it' : 'them'}: ${notDialled.map((/** @type {any} */ h) => h.name).join(', ')}. ${voice.askForMachines}; this tool does not connect to anybody's machines on its own.`
+    );
+  }
+
   if (partial.length) {
     out.push('');
-    out.push(`Reachable, but not everything on them can be watched: ${partial.map((/** @type {any} */ s) => s.name).join(', ')}. staysfixed_capabilities says what each limit is.`);
+    out.push(`Reachable, but not everything on them can be watched: ${partial.map((/** @type {any} */ s) => s.name).join(', ')}. ${voice.capabilities} says what each limit is.`);
   }
 
   if (Array.isArray(caps?.limits) && caps.limits.length) {

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/observation.js

@@ -879,13 +879,43 @@ export function wobbleStorm(wobble) {
  * and wobbles now is a finding in itself: the change made something unpredictable. Nothing is
  * "wrong" at that address and it still needs fixing.
  *
+ * AND THE CASE WHERE THERE IS NOTHING TO SUBTRACT FROM, because there was no change. When
+ * nobody has edited anything, the build being checked and the build on record as working are
+ * the same build — the same id, the same folder of stored runs — and the record of "the old
+ * build" is read back as the newest run in that folder, which is the run the LAST check left
+ * there. So an everyday check on an untouched tree compares this run against the previous run
+ * of one build and reports whatever flickered between them as a change nobody asked for.
+ *
+ * Measured 2026-08-31 on a stock Next.js app with two pages and a link between them. Next's
+ * own link prefetch is started by the browser and cancelled when the page is torn down at the
+ * end of the walk, so it lands in about four runs in five; ten checks of that untouched app,
+ * minutes apart, gave three reports of a difference, one report that "the change made
+ * something non-deterministic", and six clean ones. Identical bytes, four different answers.
+ *
+ * Two runs of one build are a wobble measurement — that is this tool's own word for it, and
+ * `measureWobble` above refuses to be handed two different builds precisely because the
+ * distinction matters. So when both sides carry the same build id, nothing here may be called
+ * a change, and nothing may be called newly unpredictable either: the address was already
+ * unpredictable and all that happened is that it was watched for longer.
+ *
+ * Nothing is hidden by this and the count does not shrink. Every difference is still counted
+ * and still named — it moves from the change list to the wobble list, where it says the true
+ * thing about the product: this address does not sit still. That is more than "1 thing
+ * behaves differently" told anybody, not less. Tell it the reference build id and it applies;
+ * leave that out and every existing caller behaves exactly as it did before.
+ *
  * @param {Difference[]} differences
  * @param {Wobble} wobble                                Measured on the candidate build.
- * @param {{referenceWobble?: Wobble, steadyInReference?: string[]}} [opts]
+ * @param {{referenceWobble?: Wobble, steadyInReference?: string[], referenceBuildId?: string, candidateBuildId?: string}} [opts]
  * @returns {WobbleSubtraction}
  */
 export function subtractWobble(differences, wobble, opts = {}) {
   const unstableNow = new Set(wobble.unstable);
+  const candidateBuildId = opts.candidateBuildId ?? wobble.buildId;
+  // Both sides have to actually name a build. An empty id means "we do not know", and two
+  // things we do not know are not the same thing — reading them as a match would quietly
+  // silence every real comparison that failed to record its build.
+  const sameBuild = Boolean(opts.referenceBuildId) && opts.referenceBuildId === candidateBuildId;
   // NOT symmetric, and that is deliberate. Subtracting the OLD build's wobble as well was
   // tried on 2026-08-30 and taken straight back out: a path the old build answered randomly
   // and the new build now answers the same way every time is a REAL change — somebody made
@@ -899,7 +929,11 @@ export function subtractWobble(differences, wobble, opts = {}) {
   const noise = [];
 
   for (const d of differences) {
-    const wobbling = unstableNow.has(d.path);
+    // Same build on both sides means the two runs being compared are two runs of ONE build,
+    // so the disagreement is the build arguing with itself whether or not this check's own
+    // two runs happened to catch it doing so. It is wobble by definition, and it is filed as
+    // wobble rather than dropped, so the address is still counted and still named.
+    const wobbling = sameBuild || unstableNow.has(d.path);
     // Copy rather than mutate: the caller's list is often the stored diff, and a flag written
     // into it becomes a fact nobody can trace back to whoever decided it.
     const flagged = { ...d, real: !wobbling, wobbling };
@@ -909,7 +943,11 @@ export function subtractWobble(differences, wobble, opts = {}) {
 
   const referenceWobble = opts.referenceWobble;
   const steadyBefore = opts.steadyInReference ? new Set(opts.steadyInReference) : null;
-  const couldTell = Boolean((referenceWobble && referenceWobble.measured) || steadyBefore);
+  // "The change made something unpredictable" needs a change to blame. With one build on both
+  // sides there was none, and the run that used to say it was reading the previous check of
+  // the same build as though it were the old build. It could not tell, and saying so is the
+  // honest answer — never "nothing became unpredictable", which claims a measurement.
+  const couldTell = !sameBuild && Boolean((referenceWobble && referenceWobble.measured) || steadyBefore);
 
   /** @type {WobbleEntry[]} */
   let newlyUnstable = [];
@@ -930,8 +968,9 @@ export function subtractWobble(differences, wobble, opts = {}) {
     noise,
     newlyUnstable,
     couldTellNewlyUnstable: couldTell,
-    note: subtractionNote(wobble, couldTell, real.length, noise.length, newlyUnstable.length),
+    note: subtractionNote(wobble, couldTell, real.length, noise.length, newlyUnstable.length, sameBuild),
   };
+  if (sameBuild) out.sameBuild = true;
   if (storm.stormy) {
     out.couldNotTell = true;
     out.couldNotTellWhy = storm.why;
@@ -949,9 +988,22 @@ export function subtractWobble(differences, wobble, opts = {}) {
  * @param {number} realCount
  * @param {number} noiseCount
  * @param {number} newlyUnstableCount
+ * @param {boolean} [sameBuild]        Both sides are one build, so none of this is a change.
  * @returns {string}
  */
-function subtractionNote(wobble, couldTell, realCount, noiseCount, newlyUnstableCount) {
+function subtractionNote(wobble, couldTell, realCount, noiseCount, newlyUnstableCount, sameBuild = false) {
+  if (sameBuild) {
+    // Said first and said plainly, because a quiet answer nobody can account for is worth
+    // nothing. This is not "we found no differences" — it is "the two things compared were
+    // one build, so a difference between them could only ever have been the build arguing
+    // with itself", and the reader needs the second sentence to trust the first.
+    const n = noiseCount;
+    return (
+      `${n === 0 ? 'Two runs of one build, and they agreed about everything.' : `${n} address${n === 1 ? '' : 'es'} answered differently across two runs of one build, which is this build disagreeing with itself and not a change anybody made.`} ` +
+      'Nothing has been edited since it was shipped, so there was nothing here that could have been a change. ' +
+      'Change the code, or ship again to cut a fresh record, to have something to compare against.'
+    );
+  }
   if (!wobble.measured) {
     return `The new build was only run once, so none of its own noise has been subtracted. All ${realCount} difference${realCount === 1 ? '' : 's'} here may include things that change on every run. Run it twice for a clean list.`;
   }