staysfixed 0.8.0 → 0.9.0

package/src/v2/doctor.js

@@ -196,7 +196,7 @@ export const CHANNELS = [
  * should be able to read it once and know what to call, what it will get back,
  * and what it must not bother asking for here.
  *
- * @param {{cwd?: string, configFile?: string, offline?: boolean}} [opts]
+ * @param {{cwd?: string, configFile?: string, offline?: boolean, machines?: boolean}} [opts]
  * @returns {Promise<Capabilities>}
  */
 export async function capabilities(opts = {}) {
@@ -218,7 +218,12 @@ export async function capabilities(opts = {}) {
 
   const [tools, hosts, repo, reference, drivers, phones, asked] = await Promise.all([
     findTools(cwd, browsers),
-    offline ? Promise.resolve(/** @type {HostReport[]} */ ([])) : reachableHosts(),
+    // Only a product that could actually run somewhere else is a reason to go looking for
+    // somewhere else. A website or a command-line tool never needs a Windows desktop, and
+    // the hosts list feeds exactly one surface: that one.
+    offline
+      ? Promise.resolve(/** @type {HostReport[]} */ ([]))
+      : reachableHosts({ dial: opts.machines === true || desktopApp !== null }),
     isRepo(root).catch(() => false),
     findReference(root),
     whatThisCopyCanDrive(),
@@ -249,7 +254,7 @@ export async function capabilities(opts = {}) {
     },
     surfaces,
     drivers,
-    covers: whatThisRunActuallyCovers(surfaces),
+    covers: whatThisRunActuallyCovers(surfaces, configFile !== null),
     browsers: {
       willOpen: browsers.chosen,
       borrowingYourOwn: browsers.borrowingHis,
@@ -1175,13 +1180,40 @@ function androidSdkTool(folder, name) {
  * answers is a runner the tool already has, and it must never appear in the
  * result as something to go and set up.
  *
+ * @param {{dial?: boolean}} [opts]
  * @returns {Promise<HostReport[]>}
  */
-export async function reachableHosts() {
+export async function reachableHosts(opts = {}) {
   if (!onPath('ssh')) return [];
   const names = await sshConfigHosts();
   if (names.length === 0) return [];
 
+  // READING the ssh config is free and tells nobody anything. DIALLING is neither, and it
+  // is not something this tool may do to somebody who has just installed it.
+  //
+  // The first command a stranger runs is `doctor`. On a brand-new scratch project with no
+  // settings file and nothing that could possibly need a second machine, this opened ssh
+  // connections to every host in their `~/.ssh/config` and ran a command on each — measured
+  // on 2026-08-30: ten hosts configured, connections out within seconds of the first run,
+  // nothing said before or after. Those are production servers in a lot of people's configs,
+  // and in a lot of workplaces that alone is a policy breach. `--offline` existed, but a way
+  // out you only learn about afterwards is not consent.
+  //
+  // So it is asked for now rather than assumed, and the machines are still NAMED either way,
+  // because a machine quietly left out of the answer is the same bug as a folder quietly
+  // skipped while reading source: the list looks complete and the runner somebody needed is
+  // simply not in it.
+  if (opts.dial !== true) {
+    return names.map(
+      (name) =>
+        /** @type {HostReport} */ ({
+          name,
+          reachable: false,
+          how: 'named in your ssh config and deliberately NOT dialled. Nothing here needs a second machine, and this tool does not connect to yours unasked. `staysfixed doctor --machines` checks them.',
+        })
+    );
+  }
+
   const dialled = await Promise.all(names.slice(0, MAX_HOSTS).map((name) => describeHost(name)));
   // Anything past the cap is NAMED rather than dropped. A machine quietly left out of
   // this list is the same shape of bug as a folder quietly skipped while reading source:
@@ -1776,6 +1808,9 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * @property {{name: string, why: string}[]} partly   Looked at, but not completely, and why.
  * @property {{name: string, why: string, whoFixes: SurfaceState}[]} notCovered
  * @property {boolean} everything    True only when nothing at all is left out.
+  * @property {boolean} [canRunHere]
+ *   False when nothing is set up in this folder, so a check cannot run here at all
+ *   whatever this machine could otherwise drive.
  */
 
 /**
@@ -1787,9 +1822,10 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
  * covers your website; your iPhone app is not being checked, and here is why.
  *
  * @param {SurfaceReport[]} surfaces
+ * @param {boolean} setUpHere   Whether a check can actually run in this folder at all.
  * @returns {Covers}
  */
-function whatThisRunActuallyCovers(surfaces) {
+function whatThisRunActuallyCovers(surfaces, setUpHere = true) {
   // Three buckets, not two. Folding "partly" into "covered" is exactly the
   // over-claim this function exists to stop: an iPhone app whose screens cannot
   // be read is not a covered iPhone app.
@@ -1813,7 +1849,23 @@ function whatThisRunActuallyCovers(surfaces) {
 
   /** @type {string[]} */
   const parts = [];
-  parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  // What this MACHINE can drive and what a check in THIS FOLDER would cover are two
+  // different questions, and only one of them was being answered. In an empty folder — no
+  // settings, no code — this said "A check here covers command-line tools and libraries and
+  // web apps and sites in full" and doctor exited 0, while `check` in that same folder
+  // refused to run at all: "No Stays Fixed config found here, so there is nothing to check."
+  // Measured 2026-08-30. `doctor --json` is the first call an agent is told to make, which
+  // is the worst place there is for a sentence with "here" in it to mean somewhere else.
+  //
+  // Everything below still says what it said — a reader needs the whole picture either way —
+  // it is just no longer written as though a check could run.
+  if (!setUpHere) {
+    out.canRunHere = false;
+    parts.push('Nothing is set up in this folder, so a check cannot run here at all and would cover nothing. Run `staysfixed init` first.');
+    parts.push(full.length > 0 ? `Once it is set up, this machine could cover ${plainList(out.covered)} in full.` : 'Even set up, this machine could cover nothing in full.');
+  } else {
+    parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+  }
   if (some.length > 0) parts.push(`It covers ${plainList(some.map((s) => s.name))} only partly — read the summary for each before treating a clean result as proof.`);
   if (missing.length > 0) {
     parts.push(`It does NOT check ${plainList(missing.map((s) => s.name))} at all, so a clean result says nothing whatever about ${missing.length === 1 ? 'that' : 'those'}.`);
@@ -1888,8 +1940,15 @@ function nextSteps(surfaces, reference, repo) {
     steps.push({
       what: 'record a reference',
       why: 'Until one build has been recorded there is nothing to compare a new one against, and a clean result would mean nothing.',
-      fix: 'staysfixed check --paired',
-      automatic: true,
+      // Both halves of this were wrong, and they were wrong in the direction that matters.
+      // `check --paired` cannot record a reference — run it twice on a fresh project and
+      // both runs answer that there is no build on record, with the reference id still
+      // empty — so anybody following this went round in a circle. And `automatic: true` told
+      // the agent this was its to do, when the one rule underneath this whole product is
+      // that only shipping cuts a reference and no agent may bless its own work. Saying an
+      // agent can do the single thing it must never do is worse than saying nothing.
+      fix: 'staysfixed ship    (only shipping records what "working" means — no agent may cut that reference)',
+      automatic: false,
       unlocks: 'Every check after this one has something to compare against, so "nothing changed" starts meaning something.',
     });
   }
@@ -2072,7 +2131,7 @@ export function describeCapabilities(caps) {
  * @returns {Promise<number>}
  */
 export async function run(ctx) {
-  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline') });
+  const caps = await capabilities({ cwd: ctx.cwd, configFile: ctx.configFile, offline: ctx.bool('offline'), machines: ctx.bool('machines') });
 
   if (ctx.bool('json')) {
     // Nothing but the object may reach standard output. Doctor is the first call

package/src/v2/escalate.js

@@ -517,7 +517,11 @@ function buildEscalations(product, record, verdict) {
       kind: 'no-reference',
       what: `There is no build of ${product} on record as working yet, so this run had nothing to compare against.`,
       why: 'Only you can say what "working" means, and you say it by shipping — no agent may cut that reference.',
-      todo: 'Ship once with the hook in place. From the next change onwards it is automatic and you will not see this again.',
+      // The order is said out loud because leaving it out sent people round a circle: `ship`
+      // on a build nothing has watched answers "run a check before the next release", and
+      // this line answered "you say it by shipping". Both are true and neither says which
+      // comes first. A check watches the build; shipping then blesses what was watched.
+      todo: 'Run `staysfixed check` once so there is a build to bless, then `staysfixed ship`. From the next change onwards it is automatic and you will not see this again.',
     });
   }
 

package/src/v2/init.js

@@ -824,7 +824,10 @@ function sortNeeds(readiness, project, machine) {
       what: 'one build on record as working',
       why: 'Until one build has been recorded there is nothing to compare a new one against, and a clean result would mean nothing at all.',
       unlocks: 'every check from then on',
-      fix: 'staysfixed check --paired    (or ship once with `staysfixed ship` at the end of your release)',
+      // `check --paired` was named here first, and it does not do this: run it twice on a
+      // fresh project and both runs answer "there is no build on record as working". Only
+      // shipping cuts a reference, on purpose — no agent may bless its own work.
+      fix: 'staysfixed ship    (only shipping records what "working" means — run it once at the end of your release)',
       who: 'the agent',
     });
   }
@@ -1148,7 +1151,10 @@ export function configText(project) {
   w('  // "working" means, so the name is how two of them are told apart.');
   if (project.products.length > 1) {
     w('  // This repository makes more than one thing. A check covers whichever of them the');
-    w('  // settings below describe; run the others with `staysfixed check --product <name>`.');
+    // `--product` is not an option on `check` and never has been. Naming it here sent people
+    // to a flag the CLI rejects, in the settings file the tool itself wrote for them.
+    w('  // settings below describe. To check one of the others, run `staysfixed check` from');
+    w('  // inside that package, or point at its settings with `--config <file>`.');
   }
   w(`  product: ${JSON.stringify(project.name)},`);
   w('');
@@ -1342,7 +1348,12 @@ export function configText(project) {
   } else if (project.pages.length > 0) {
     w(`${webOn}// ${project.pages.length} page address${project.pages.length === 1 ? '' : 'es'} are read out of your folder names automatically — nothing to list here.`);
     w(`${webOn}// Add a screen only for something a walk has to DO rather than just open:`);
-    w(`${webOn}// screens: [{ name: 'signing in', url: '/login', steps: [{ fill: '#email', with: 'a@b.c' }, { click: 'Sign in' }] }],`);
+    // `fill:` and `with:` are not words this tool knows — the verb is `type:` and the value
+    // is `text:`. An unknown key used to be skipped in silence, so this example, handed to
+    // every stranger with a sign-in, filled nothing, clicked Sign in on an empty form, and
+    // then photographed the login page for every screen behind the wall while reporting a
+    // clean run. The example that teaches the vocabulary has to be IN the vocabulary.
+    w(`${webOn}// screens: [{ name: 'signing in', url: '/login', steps: [{ type: '#email', text: 'a@b.c' }, { type: '#password', text: 'secret' }, { click: 'Sign in' }] }],`);
   } else {
     w(`${webOn}// screens: [{ name: 'the front page', url: '/' }],`);
   }
@@ -1600,9 +1611,14 @@ function nextCommands(readiness, project) {
   if (reachable.length > 0) {
     next.push({
       command: 'staysfixed check --paired',
+      // It does NOT record what "working" means, and saying so here sent everybody round a
+      // loop: run it, be told there is no build on record, run it again, be told the same
+      // thing. Only `ship` cuts a reference — that is the rule the whole product rests on,
+      // because an agent that can bless its own work is not a safety net. So this says what
+      // the run actually does, and `ship` below says what only it can do.
       what: reachable.some((r) => r.state === 'ready')
-        ? 'The first real run. It records what working looks like, so later runs have something to compare against.'
-        : 'The first real run. Nothing here is fully set up yet, so it records what it can reach and says plainly what it left out — which is more useful than waiting.',
+        ? 'The first real run. It walks everything and shows you what it sees. It cannot record what "working" means — only shipping does that.'
+        : 'The first real run. Nothing here is fully set up yet, so it walks what it can reach and says plainly what it left out — which is more useful than waiting.',
     });
   }
   if (project.tests.files > 0) {

package/src/v2/mcp/tools.js

@@ -823,7 +823,12 @@ async function toolCheck(ctx, input) {
   );
 
   const page = unaccounted.slice(offset, offset + limit);
-  const clean = unaccounted.length === 0 && newlyUnstable.length === 0 && result?.blocked !== true;
+  // A run that compared NOTHING is not a clean run, and this is the surface where saying so
+  // matters most. The engine had already worked it out and set `ok: false`; this line only
+  // ever counted differences, so a project with nothing on record produced zero differences,
+  // counted as clean, and the agent was told everything still works.
+  const comparedNothing = typeof result?.comparedNothing === 'string' && result.comparedNothing.length > 0;
+  const clean = cleanForAgent(result, unaccounted.length, newlyUnstable.length);
 
   // What this run did not look at, in the engine's own words. It rides in every reply,
   // clean ones included: a green result on a product with three hundred unopened doors is
@@ -843,7 +848,16 @@ async function toolCheck(ctx, input) {
   if (input.format === 'json') {
     const payload = {
       ok: clean,
-      verdict: result?.blocked ? 'blocked' : clean ? 'nothing unaccounted for' : 'differences found',
+      // "differences found" would be the wrong word for a run that found none because it
+      // compared none. There are three outcomes here, not two, and the third is the one
+      // that must never be mistaken for either.
+      verdict: result?.blocked
+        ? 'blocked'
+        : comparedNothing
+          ? 'nothing was compared'
+          : clean
+            ? 'nothing unaccounted for'
+            : 'differences found',
       mode: result?.mode ?? null,
       note: result?.summary ?? null,
       noiseRemoved: result?.differencesNoise ?? null,
@@ -866,7 +880,14 @@ async function toolCheck(ctx, input) {
         waiversLeft: accounting?.left ?? null,
         note: accounting?.note ?? null,
       },
-      findings: page,
+      // The class an agent reads has to be the class that DECIDES things, not the engine's
+      // first guess. A 20% markup on a price came back as `class: "ordinary"` here while the
+      // human text on the same run said "1 of them sealed and not yours to waive" and
+      // `staysfixed_waive` refused it outright because it touches money. An agent reading
+      // "ordinary" would reasonably believe it may wave a price change through, and would
+      // tell somebody so. `waivable` is spelled out beside it so nothing has to be inferred
+      // from a word at all.
+      findings: page.map(findingForAgent),
       aimedAt: aimed ? { surface: surface ?? 'auto', at: at ?? null, confirmed: missedTheTarget === null } : null,
       aimingWarning: missedTheTarget,
     };
@@ -913,6 +934,53 @@ async function toolCheck(ctx, input) {
   return { content: [{ type: 'text', text: body + tail }], isError: !clean };
 }
 
+/**
+ * Is this a clean run, as far as the machine asking is concerned?
+ *
+ * The last line is the one that matters and it is the one that was missing. This surface
+ * used to work "clean" out from the difference count ALONE, and a product with nothing on
+ * record produces no differences — so zero differences counted as a pass, and an agent was
+ * told "everything that worked before still works" about a run that compared nothing at all.
+ * The engine had already decided; nobody asked it.
+ *
+ * So the engine's own verdict is the floor. Whatever else is true, this can never answer
+ * clean about a run the engine called not-ok. Counting reasons here will always be a list
+ * somebody forgets to add to; deferring to the decision already made cannot be.
+ *
+ * @param {any} result            What `check` returned.
+ * @param {number} unaccounted    Differences nobody has accounted for.
+ * @param {number} newlyUnstable  Addresses that were steady and are not any more.
+ * @returns {boolean}
+ */
+export function cleanForAgent(result, unaccounted, newlyUnstable) {
+  if (result && result.ok === false) return false;
+  if (result && result.blocked === true) return false;
+  if (result && typeof result.comparedNothing === 'string' && result.comparedNothing.length > 0) return false;
+  return unaccounted === 0 && newlyUnstable === 0;
+}
+
+/**
+ * One finding, shaped for the machine that reads it.
+ *
+ * Split out and exported because it is a DECISION, not formatting, and a decision only a
+ * running MCP server can reach is one nobody notices breaking. The class an agent reads has
+ * to be the class that decides things: a 20% markup on a price came back over MCP as
+ * `class: "ordinary"` while the human text on the same run said "1 of them sealed and not
+ * yours to waive" and `staysfixed_waive` refused it because it touches money. An agent
+ * reading "ordinary" would reasonably believe it may wave a price change through, and would
+ * say so to a person. `waivable` is spelled out beside it so nothing has to be inferred
+ * from a word at all.
+ *
+ * @param {any} f
+ * @returns {any}
+ */
+export function findingForAgent(f) {
+  const sealed = classify(f);
+  return sealed
+    ? { ...f, class: sealed.class, sealed: true, waivable: false, sealedBecause: sealed.why, sealedBy: sealed.matched }
+    : { ...f, sealed: false, waivable: true };
+}
+
 /**
  * @param {object} a
  * @param {CheckResult} a.result
@@ -931,7 +999,7 @@ async function toolCheck(ctx, input) {
  * @param {string|null} a.covers
  * @returns {string}
  */
-function renderCheck({ result, unaccounted, page, offset, limit, waived, expired, waiversLeft, newlyUnstable, intent, clean, missedTheTarget, notChecked, covers }) {
+export function renderCheck({ result, unaccounted, page, offset, limit, waived, expired, waiversLeft, newlyUnstable, intent, clean, missedTheTarget, notChecked, covers }) {
   /** @type {string[]} */
   const out = [];
 
@@ -942,7 +1010,14 @@ function renderCheck({ result, unaccounted, page, offset, limit, waived, expired
     return out.join('\n');
   }
 
-  if (clean) {
+  if (result?.comparedNothing) {
+    out.push(
+      result.comparedNothing === 'no reference'
+        ? 'NOTHING WAS ACTUALLY COMPARED. There is no build of this product on record as working, so this run had nothing whatever to hold today\'s behaviour against. This is not a pass and not a failure - it is no answer.'
+        : 'NOTHING WAS ACTUALLY COMPARED. Every journey was walked, and not one of them had anything on record from the build you were happy with. This is not a pass and not a failure - it is no answer.',
+    );
+    out.push('Do not report this as a clean run. Only shipping records what "working" means, and no agent may cut that reference.');
+  } else if (clean) {
     out.push('NOTHING UNACCOUNTED FOR. Everything that worked before still works, as far as this run could see.');
   } else if (unaccounted.length) {
     const sealed = unaccounted.filter((f) => classify(f) !== null).length;

package/src/v2/reference.js

@@ -233,6 +233,82 @@ async function readJson(file, fallback) {
   }
 }
 
+/**
+ * Read a JSON file, change it, and write it back with nobody else doing the same thing at
+ * the same time.
+ *
+ * `writeJsonAtomic` makes each individual write whole — nobody ever reads half a file. It
+ * does nothing at all about two processes READING the same file, each appending to what they
+ * read, and each writing their own version over the other's. Measured on 2026-08-30: six
+ * `staysfixed ship` commands started at once on one project, all six reported success, four
+ * of them each believed they were cutting the very first reference — and four records
+ * survived out of six. This is an MCP server. Two agents shipping at once is not an exotic
+ * case, it is the design.
+ *
+ * The lock is a directory, because creating one either succeeds or fails and never half
+ * happens, on every platform this runs on. A lock far older than any write could take is
+ * rubbish left behind by a killed process and is taken. Waiting for ever is worse than the
+ * bug, so after a long wait it is taken anyway — losing a record is bad, and a release that
+ * hangs is worse.
+ *
+ * @template T
+ * @param {string} file
+ * @param {(current: T) => T | Promise<T>} change
+ * @param {T} fallback
+ * @returns {Promise<T>}
+ */
+async function updateJsonAtomic(file, change, fallback) {
+  return await withLock(`${file}.lock`, async () => {
+    const next = await change(await readJson(file, fallback));
+    await writeJsonAtomic(file, next);
+    return next;
+  });
+}
+
+/**
+ * Do something with nobody else doing it at the same time, across processes.
+ *
+ * A directory is the lock, because creating one either succeeds or fails and never half
+ * happens, on every platform this runs on. A lock far older than the work could take is
+ * rubbish left behind by a killed process and is taken. Waiting for ever is worse than the
+ * bug it prevents, so after a long wait it is taken anyway: losing a record is bad, and a
+ * release that never returns is worse.
+ *
+ * @template T
+ * @param {string} lock
+ * @param {() => Promise<T>} work
+ * @returns {Promise<T>}
+ */
+async function withLock(lock, work) {
+  const STALE_MS = 30_000;
+  const GIVE_UP_MS = 15_000;
+  await fsp.mkdir(path.dirname(lock), { recursive: true });
+  const startedAt = Date.now();
+  for (;;) {
+    try {
+      await fsp.mkdir(lock);
+      break;
+    } catch {
+      let age = 0;
+      try {
+        age = Date.now() - (await fsp.stat(lock)).mtimeMs;
+      } catch {
+        continue; // It went away between the failure and the question. Try again.
+      }
+      if (age > STALE_MS || Date.now() - startedAt > GIVE_UP_MS) {
+        await fsp.rm(lock, { recursive: true, force: true }).catch(() => {});
+        continue;
+      }
+      await new Promise((done) => setTimeout(done, 15 + Math.floor(Math.random() * 35)));
+    }
+  }
+  try {
+    return await work();
+  } finally {
+    await fsp.rm(lock, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
 /**
  * A sortable, file-safe id for one cut.
  * @param {Date} [now]
@@ -868,6 +944,32 @@ export async function cutReference(store, opts) {
 
   await ensureStore(store);
 
+  // ONE AT A TIME, PER PRODUCT. Everything below reads the current reference, decides
+  // whether this build is already it, moves the pointer, retires waivers and writes the log
+  // — and until 2026-08-30 nothing stopped two of them doing all of that at once.
+  //
+  // Measured: six `staysfixed ship` commands started together on one project. All six
+  // reported success. FOUR of them each said "Nothing was being compared against before
+  // this", because all four had read an empty reference and none had seen the others. Four
+  // records survived out of six, and the "already the reference, change nothing" path — the
+  // one that stops a release script running twice from writing history twice — never fired
+  // once. This is an MCP server: two agents shipping at once is the design, not an exotic
+  // case, and the file they were racing on is the one that defines what "working" means.
+  return await withLock(path.join(store.dir, `cut.${safeName(product)}.lock`), async () =>
+    cutReferenceHoldingTheLock(store, opts, product, buildId),
+  );
+}
+
+/**
+ * The cut itself, with the lock already held.
+ *
+ * @param {Store} store
+ * @param {any} opts
+ * @param {string} product
+ * @param {string} buildId
+ * @returns {Promise<ReferenceCut>}
+ */
+async function cutReferenceHoldingTheLock(store, opts, product, buildId) {
   const decision = await shouldCut(store, product, opts.build);
   if (!decision.ok && opts.force !== true) {
     throw new StaysFixedError(decision.refusal ?? decision.why, {
@@ -977,20 +1079,24 @@ function summarise(cut, name, decision) {
  */
 async function appendToLog(store, cut) {
   const file = fileIn(store, 'reference-log.json');
-  /** @type {ReferenceCut[]} */
-  const log = await readJson(file, /** @type {ReferenceCut[]} */ ([]));
-  const all = [...(Array.isArray(log) ? log : []), cut];
-
-  if (all.length > MAX_LOG_ENTRIES) {
-    const overflow = all.slice(0, all.length - MAX_LOG_ENTRIES);
-    const archiveFile = fileIn(store, 'reference-log-archive.json');
-    /** @type {ReferenceCut[]} */
-    const archive = await readJson(archiveFile, /** @type {ReferenceCut[]} */ ([]));
-    await writeJsonAtomic(archiveFile, [...(Array.isArray(archive) ? archive : []), ...overflow]);
-    await writeJsonAtomic(file, all.slice(-MAX_LOG_ENTRIES));
-    return;
-  }
-  await writeJsonAtomic(file, all);
+  const archiveFile = fileIn(store, 'reference-log-archive.json');
+  await updateJsonAtomic(
+    file,
+    async (log) => {
+      const all = [...(Array.isArray(log) ? log : []), cut];
+      if (all.length > MAX_LOG_ENTRIES) {
+        const overflow = all.slice(0, all.length - MAX_LOG_ENTRIES);
+        await updateJsonAtomic(
+          archiveFile,
+          (archive) => [...(Array.isArray(archive) ? archive : []), ...overflow],
+          /** @type {ReferenceCut[]} */ ([]),
+        );
+        return all.slice(-MAX_LOG_ENTRIES);
+      }
+      return all;
+    },
+    /** @type {ReferenceCut[]} */ ([]),
+  );
 }
 
 /**

package/src/v2/ship.js

@@ -417,6 +417,32 @@ async function resolveBuild(store, product, release, told, onProblem) {
     return typeof told === 'string' ? { id: told, product } : told;
   }
 
+  // WHAT IS ACTUALLY HERE, before what the commit says is here.
+  //
+  // Matching on the commit alone blesses the wrong thing the moment the tree is dirty:
+  // several builds share one commit, this took the first of them, and that is usually an
+  // EARLIER build — one that was checked and came back clean. So editing a file and running
+  // `staysfixed ship` answered "was already the reference — nothing changed" and exited 0,
+  // about a tree nothing had ever looked at. Measured 2026-08-30 by deleting a button and
+  // shipping without a check.
+  //
+  // A dirty tree therefore has to match EXACTLY, on the fingerprint of what is on disk right
+  // now. If nothing on record is that tree, then this tree has not been checked, and the
+  // honest answer is the one the tool already knows how to give: no record of this build, so
+  // the reference does not move.
+  try {
+    const { fingerprintWorkingTree } = await import('./check.js');
+    const here = await fingerprintWorkingTree(store.root, product);
+    if (here?.id) {
+      const exact = builds.find((b) => b.fingerprint.id === here.id);
+      if (exact) return exact.fingerprint;
+      if (here.dirty) return null;
+    }
+  } catch {
+    // No git, or the tree could not be read. The joins below are all that is left, and they
+    // are better than refusing to record a release at all.
+  }
+
   const sha = release.gitSha;
   if (sha) {
     const sameCommit = builds.filter((b) => b.fingerprint.gitSha === sha);