staysfixed 0.8.0 → 0.9.1

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

package/src/v2/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/sealed.js

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

package/src/v2/ship.js

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