@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/verify.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * verify.mjs  -  "is this install the thing that was published".
+ *
+ * Two questions, and they fail in different directions.
+ *
+ * 1. PACKAGE. Every file the package shipped, against the SHA-256 recorded in
+ *    manifest.json at publish time. A file that differs was edited after
+ *    install or arrived damaged; a file that is missing was never written.
+ * 2. INSTALL. ~/.claude holds a COPY of the package's pipeline tree, made by
+ *    install.js. From the moment it is written the two drift independently,
+ *    and both directions are real: an edit in ~/.claude is a change with no
+ *    source, and a file the installer skipped is a script the docs describe
+ *    and nobody has.
+ *
+ * Only the Claude tree is compared byte for byte. The Copilot and Codex trees
+ * are path-rewritten by the installer on purpose, so a byte difference there is
+ * the design rather than the bug, and they are reported as counts.
+ *
+ * What a green result means, stated plainly because the opposite is easy to
+ * imply: it means the bytes match what the publisher recorded. It is not proof
+ * of who published them. The manifest, the signature and this verifier all
+ * travel inside the same tarball, so anyone able to rewrite one can rewrite the
+ * others - provenance is npm's integrity field, not ours. This catches damage,
+ * partial installs and post-install edits, which are the failures that actually
+ * happen.
+ *
+ * Usage:
+ *   verify.mjs                 both questions, human output
+ *   verify.mjs --package       package integrity only
+ *   verify.mjs --install       install drift only
+ *   verify.mjs --json
+ *
+ * Exit codes:
+ *   0  everything matches
+ *   1  a difference was found
+ *   2  nothing to verify (no manifest - a dev checkout, or a pre-manifest version)
+ */
+
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const MANIFEST = join(ROOT, "manifest.json");
+
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const json = has("--json");
+
+/**
+ * The ed25519 public key a signature is checked against. It comes from the
+ * environment and nothing is pinned in this file yet - so on a stock install a
+ * signed manifest reports "signed, no public key to check it against" rather
+ * than claiming valid. That is the honest state: a signature nobody can check
+ * is not a signature that passed, and hard-coding a key here before there is a
+ * release key to hard-code would be the opposite.
+ */
+const PUBLIC_KEY = process.env.MULTI_AGENT_SIGNING_PUBKEY || "";
+
+const sha256 = (p) => createHash("sha256").update(readFileSync(p)).digest("hex");
+
+/**
+ * Walk a tree, following symlinks but never twice.
+ *
+ * Following them is required rather than optional: `install --link` puts a
+ * symlink at ~/.claude/scripts, and a walker that skipped symlinks would report
+ * a linked install as entirely missing. The cost is that a link pointing at an
+ * ancestor turns the walk into a loop, so every directory is recorded by its
+ * RESOLVED path and visited once.
+ */
+function walk(dir, base = dir, out = [], seen = new Set()) {
+  let real;
+  try {
+    real = realpathSync(dir);
+  } catch {
+    return out;
+  }
+  if (seen.has(real)) return out;
+  seen.add(real);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const name of entries) {
+    if (name === ".DS_Store" || name === "__pycache__") continue;
+    const abs = join(dir, name);
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walk(abs, base, out, seen);
+    else out.push(relative(base, abs));
+  }
+  return out;
+}
+
+// --- 1. package integrity ----------------------------------------------------
+
+function verifyPackage() {
+  const manifest = JSON.parse(readFileSync(MANIFEST, "utf-8"));
+  const changed = [];
+  const missing = [];
+  for (const [rel, want] of Object.entries(manifest.files)) {
+    const abs = join(ROOT, rel);
+    if (!existsSync(abs)) {
+      missing.push(rel);
+      continue;
+    }
+    if (sha256(abs) !== want) changed.push(rel);
+  }
+
+  let signature = "unsigned";
+  const sigPath = join(ROOT, "manifest.sig");
+  if (existsSync(sigPath)) {
+    if (!PUBLIC_KEY) signature = "signed, no public key to check it against";
+    else {
+      try {
+        const ok = cryptoVerify(
+          null,
+          Buffer.from(readFileSync(MANIFEST)),
+          createPublicKey(PUBLIC_KEY),
+          Buffer.from(readFileSync(sigPath, "utf-8").trim(), "base64"),
+        );
+        signature = ok ? "valid" : "INVALID";
+      } catch (err) {
+        signature = `unverifiable: ${err?.message ?? err}`;
+      }
+    }
+  }
+
+  return {
+    version: manifest.version,
+    commit: manifest.commit,
+    fileCount: manifest.fileCount,
+    changed,
+    missing,
+    signature,
+    ok: changed.length === 0 && missing.length === 0 && signature !== "INVALID",
+  };
+}
+
+// --- 2. install drift --------------------------------------------------------
+
+/**
+ * The trees install.js writes into ~/.claude, and how each one may be compared.
+ * Kept as data rather than asked of the installer, because the installer's job
+ * is to WRITE them and a verifier that asks the writer what it wrote proves
+ * nothing.
+ *
+ * `bytes` means the copy is verbatim and a difference is drift. `presence` is
+ * for commands/, where install.js rewrites each SKILL.md's `description` into
+ * the user's outputLanguage - every file differs there BY DESIGN, so comparing
+ * bytes would report 57 findings on a healthy machine and teach everyone to
+ * ignore the whole report.
+ */
+const CLAUDE_TREES = [
+  ["scripts", "scripts", "bytes"],
+  ["lib", "lib", "bytes"],
+  ["multi-agent-refs", "multi-agent-refs", "bytes"],
+  ["agents", "agents", "bytes"],
+  ["commands/multi-agent", "commands/multi-agent", "presence"],
+];
+
+/**
+ * Files the package carries but the installer deliberately does not write:
+ * smokes, linters, fixtures and the rest of the maintainer surface. Without
+ * this filter every one of them reads as "the installer skipped a file", which
+ * is 251 false findings on a correct install.
+ */
+async function devOnly() {
+  try {
+    const mod = await import(new URL("../../install/_dev-only-files.mjs", import.meta.url).href);
+    return mod.isDevOnlyScript;
+  } catch {
+    // No filter available: say so by filtering nothing, and let the counts be
+    // wrong loudly rather than silently.
+    return null;
+  }
+}
+
+async function verifyInstall() {
+  const home = homedir();
+  const claude = join(home, ".claude");
+  if (!existsSync(claude)) {
+    return { present: false, reason: "no ~/.claude on this machine", ok: true, trees: [] };
+  }
+
+  const isDevOnly = await devOnly();
+  const trees = [];
+  let differing = 0;
+  let absent = 0;
+  for (const [srcRel, dstRel, mode] of CLAUDE_TREES) {
+    const src = join(ROOT, "pipeline", srcRel);
+    const dst = join(claude, dstRel);
+    if (!existsSync(src)) continue;
+    const srcFiles = walk(src).filter(
+      (rel) => !(srcRel === "scripts" && isDevOnly && isDevOnly(rel)),
+    );
+    const changed = [];
+    const missing = [];
+    for (const rel of srcFiles) {
+      const b = join(dst, rel);
+      if (!existsSync(b)) {
+        missing.push(rel);
+        continue;
+      }
+      if (mode === "bytes" && sha256(join(src, rel)) !== sha256(b)) changed.push(rel);
+    }
+    differing += changed.length;
+    absent += missing.length;
+    trees.push({ tree: dstRel, mode, files: srcFiles.length, changed, missing });
+  }
+
+  const others = [".copilot", ".codex"].filter((h) => existsSync(join(home, h)));
+
+  return {
+    present: true,
+    trees,
+    differing,
+    absent,
+    otherHosts: others,
+    ok: differing === 0 && absent === 0,
+  };
+}
+
+// --- output ------------------------------------------------------------------
+
+async function main() {
+  const wantPackage = has("--package") || !has("--install");
+  const wantInstall = has("--install") || !has("--package");
+
+  if (wantPackage && !existsSync(MANIFEST)) {
+    const msg =
+      "no manifest.json - this is a source checkout or a version published before manifests existed";
+    if (json)
+      process.stdout.write(`${JSON.stringify({ kind: "UNVERIFIABLE", reason: msg }, null, 2)}\n`);
+    else process.stdout.write(`UNVERIFIABLE: ${msg}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const pkg = wantPackage ? verifyPackage() : null;
+  const inst = wantInstall ? await verifyInstall() : null;
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ package: pkg, install: inst }, null, 2)}\n`);
+  } else {
+    if (pkg) {
+      process.stdout.write(
+        `paket: ${pkg.version} (${pkg.commit?.slice(0, 12) ?? "commit bilinmiyor"}) - ${pkg.fileCount} dosya, imza: ${pkg.signature}\n`,
+      );
+      if (!pkg.changed.length && !pkg.missing.length)
+        process.stdout.write("  butun dosyalar yayinlandigi gibi\n");
+      const SHOWN = 20;
+      for (const f of pkg.changed.slice(0, SHOWN)) process.stdout.write(`  ! degismis: ${f}\n`);
+      for (const f of pkg.missing.slice(0, SHOWN)) process.stdout.write(`  ! eksik:    ${f}\n`);
+      // Counted per list against what was actually PRINTED. Subtracting a flat
+      // 40 from the combined total spent a budget the lists had not used: with
+      // 25 changed and 0 missing it printed 20, hid 5, and said nothing - a
+      // tampered install under-reported by up to twenty files with no sign.
+      const hidden =
+        Math.max(0, pkg.changed.length - SHOWN) + Math.max(0, pkg.missing.length - SHOWN);
+      if (hidden > 0) process.stdout.write(`  ... ve ${hidden} dosya daha\n`);
+    }
+    if (inst) {
+      if (!inst.present) process.stdout.write(`kurulum: ${inst.reason}\n`);
+      else {
+        const total = inst.trees.reduce((a, t) => a + t.files, 0);
+        process.stdout.write(
+          `kurulum: ~/.claude - ${inst.trees.length} agac, ${total} dosya karsilastirildi\n`,
+        );
+        for (const t of inst.trees) {
+          if (!t.changed.length && !t.missing.length) continue;
+          const how =
+            t.mode === "presence" ? " (yalnizca varlik: aciklamalar kurulumda cevriliyor)" : "";
+          process.stdout.write(
+            `  ${t.tree}: ${t.changed.length} farkli, ${t.missing.length} eksik${how}\n`,
+          );
+          for (const f of [...t.changed.slice(0, 5)]) process.stdout.write(`    ! ${f}\n`);
+          for (const f of [...t.missing.slice(0, 5)])
+            process.stdout.write(`    ? ${f} (hic yazilmamis)\n`);
+        }
+        if (inst.ok) process.stdout.write("  kaynakla birebir ayni\n");
+        if (inst.otherHosts.length)
+          process.stdout.write(
+            `  ${inst.otherHosts.join(", ")} kurulu - yollari kurulumda yeniden yazildigi icin bayt karsilastirmasi yapilmadi\n`,
+          );
+      }
+    }
+  }
+
+  const bad = (pkg && !pkg.ok) || (inst && !inst.ok);
+  process.exitCode = bad ? 1 : 0;
+}
+
+// Importable AND runnable: index.js calls main() for `multi-agent-pipeline
+// verify`, and the direct-run guard keeps a bare `node verify.mjs` behaving
+// the same way every other script here does.
+export { main };
+
+/**
+ * realpath, not a string compare against argv[1]. Two ordinary situations break
+ * the naive form: macOS hands out /var/folders/... paths that resolve to
+ * /private/var/folders/..., and `install --link` puts a SYMLINK at
+ * ~/.claude/scripts/verify.mjs - in both cases import.meta.url is the resolved
+ * path, argv[1] is not, and the script silently does nothing at all.
+ */
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  runMain("verify", main);
+}

package/pipeline/scripts/worktree-finalize.sh

@@ -28,7 +28,7 @@
 #   0  removed (or dry-run that would remove)
 #   3  SKIPPED by a safety precondition  -  not an error, reason is reported
 #   1  usage / hard error
-set -uo pipefail
+set -euo pipefail
 
 WORKTREE=""; PROJECT_ROOT=""; TASK_ID=""; PROJECT=""; BRANCH=""
 LOGS_ROOT="${HOME}/.claude/logs/multi-agent"
@@ -97,6 +97,10 @@ skip() { REASON="$1"; emit; exit 3; }
 # preference at all, because turning it off appears to work and does nothing.
 PREFS="${PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
 if [ -f "$PREFS" ] && command -v node >/dev/null 2>&1; then
+  # `|| echo true` on the far side already covers a node that throws: an
+  # unreadable preference file reads as "not set", which is the default. Noted
+  # here because it is the one assignment in this file that was ALREADY safe
+  # under `set -e`, and the next reader should not have to re-derive that.
   enabled="$(node -e '
     const fs=require("fs");
     try {
@@ -173,6 +177,9 @@ fi
 # alternatives are end-anchored  -  unanchored, `.build.log.old` was forgiven here
 # but not deletable below, which made every removal refuse forever.
 ARTIFACTS_RE='^(agent-state\.json|phase-tracker\.json|triage-output\.json|\.review-diff\.txt|\.build\.log|\.test\.log)$|^\.pipeline/'
+# Forgiven at the end of the pipeline (see below): a worktree whose git dir is
+# already gone reports nothing, and "nothing dirty" is the correct reading of
+# that - aborting would strand the removal this function exists to perform.
 dirty="$(git -C "$rp_wt" status --porcelain 2>/dev/null | awk '
   {
     st = substr($0, 1, 2); path = substr($0, 4);
@@ -183,7 +190,7 @@ dirty="$(git -C "$rp_wt" status --porcelain 2>/dev/null | awk '
       continue   # our own untracked artefact
     fi
     printf '%s\n' "$path"
-  done)"
+  done || true)"
 if [ -n "$dirty" ]; then
   first="$(printf '%s\n' "$dirty" | head -1)"
   skip "worktree has uncommitted changes (e.g. $first)  -  refusing to remove"
@@ -219,7 +226,9 @@ copy_one() {
     SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
     return 0
   fi
-  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null
+  # Forgiven: this function already tolerates a copy that does not happen, and
+  # aborting here would skip the worktree removal that follows.
+  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null || true
   [ -d "$DEST/$1" ] && rm -rf "${DEST:?}/$1"
   cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
 }
@@ -240,7 +249,7 @@ copy_from_logs() {
     SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
     return 0
   fi
-  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null
+  mkdir -p "$DEST/$(dirname "$1")" 2>/dev/null || true
   cp -R "$src" "$DEST/$1" 2>/dev/null && SALVAGED="${SALVAGED:+$SALVAGED,}\"$1\""
 }
 

package/pipeline/scripts/write-state.mjs

@@ -16,12 +16,22 @@
  *
  *   # Replace: full overwrite from stdin JSON
  *   cat new-state.json | node write-state.mjs --replace /path/to/agent-state.json
+ *   cat patch.json | node write-state.mjs --if-rev=7 /path/to/agent-state.json
+ *
+ * `--if-rev=<n>` is compare-and-swap: write only if the record on disk is
+ * still at revision n. The lock closes the window between two WRITERS; it does
+ * nothing about the one between a read and a write, which is where an editor
+ * lives - `/multi-agent:steer` reads the state, a human thinks, and the run may
+ * move three phases before the edit lands. Without this the edit merges over
+ * the top and reinstates decisions the run already replaced.
  *
  * Exit codes:
  *   0  -  write succeeded
  *   1  -  invalid JSON on stdin
  *   2  -  lock timeout (another writer held the lock past the acquire window)
+ *   4  -  the lock was taken from us mid-write; nothing was written, retry
  *   3  -  I/O error (disk full, permission denied, parent dir missing)
+ *   5  -  --if-rev did not match; the record moved, nothing was written
  *
  * Tunables (env):
  *   WRITE_STATE_LOCK_TIMEOUT_MS  acquire window before exit 2 (default 15000)
@@ -52,9 +62,11 @@ import {
 } from "fs";
 import { dirname, basename } from "path";
 import { Buffer } from "node:buffer";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 /**
- * @typedef {{ replace: boolean, path: string }} ParsedArgs
+ * @typedef {{ replace: boolean, path: string, ifRev: number|null }} ParsedArgs
  */
 
 /** @returns {ParsedArgs} */
@@ -62,18 +74,26 @@ function parseArgs() {
   const args = process.argv.slice(2);
   let replace = false;
   let path = null;
+  let ifRev = null;
   for (const a of args) {
     if (a === "--replace") replace = true;
-    else if (a.startsWith("--")) {
+    else if (a.startsWith("--if-rev=")) {
+      const v = Number(a.slice("--if-rev=".length));
+      if (!Number.isInteger(v) || v < 0) {
+        console.error(`write-state: --if-rev takes a non-negative integer, got ${a.slice(9)}`);
+        process.exit(3);
+      }
+      ifRev = v;
+    } else if (a.startsWith("--")) {
       console.error(`write-state: unknown flag ${a}`);
       process.exit(3);
     } else path = a;
   }
   if (!path) {
-    console.error("usage: write-state.mjs [--replace] <path>");
+    console.error("usage: write-state.mjs [--replace] [--if-rev=<n>] <path>");
     process.exit(3);
   }
-  return { replace, path };
+  return { replace, path, ifRev };
 }
 
 /**
@@ -103,8 +123,13 @@ async function acquireLock(
     try {
       writeFileSync(stagePath, String(process.pid));
       linkSync(stagePath, lockPath); // fails EEXIST if another writer holds it
+      // The inode of the lock WE created. Everything after this point checks
+      // against it: a lock at the same path with a different inode is somebody
+      // else's, and both releasing it and writing under it are the same bug the
+      // reclaim path below already refuses to commit.
+      const ino = statSync(lockPath).ino;
       unlinkSync(stagePath);
-      return;
+      return ino;
     } catch (err) {
       try {
         unlinkSync(stagePath);
@@ -208,16 +233,46 @@ function lockIdentityIfStale(lockPath, staleMs) {
 // Path whose lock this process currently holds (null when none). Lets the
 // top-level error handler release our lock on unexpected failures.
 let heldLockFor = null;
+// The inode of that lock. The path alone does not identify it: a lock deleted
+// and re-created at the same path is a different file and a different owner.
+let heldLockIno = null;
+
+/**
+ * True when the lock at `path` is still the one this process created.
+ *
+ * @param {string} path
+ * @param {number | null} ino
+ * @returns {boolean}
+ */
+function stillOurs(path, ino) {
+  if (ino === null) return true; // nothing was ever locked; nothing to lose
+  try {
+    return statSync(`${path}.lock`).ino === ino;
+  } catch {
+    return false; // our lock is gone, which means somebody removed it
+  }
+}
 
 /** @param {string} path */
-function releaseLock(path) {
+function releaseLock(path, ino = heldLockIno) {
   const lockPath = `${path}.lock`;
   try {
+    // By identity, never by path - the same rule acquireLock states and this
+    // function used to break. If our lock was reclaimed as stale while we were
+    // starved (the abandon ceiling, or the unreadable-PID window), the lock now
+    // at this path belongs to a LIVE writer, and unlinking it puts two writers
+    // inside at once and loses one update. That is the third point in this
+    // cycle where "delete by path" produces the same data loss; the other two
+    // are documented in acquireLock.
+    if (ino !== null && statSync(lockPath).ino !== ino) return;
     unlinkSync(lockPath);
   } catch {
     /* already gone  -  fine */
   }
-  if (heldLockFor === path) heldLockFor = null;
+  if (heldLockFor === path) {
+    heldLockFor = null;
+    heldLockIno = null;
+  }
 }
 
 /**
@@ -225,6 +280,22 @@ function releaseLock(path) {
  * @param {object} patch
  * @returns {object}
  */
+/**
+ * The version a NEWLY created state document is stamped with, read from the
+ * schema so the writer and the schema cannot disagree. The literal is a
+ * fallback for an unreadable schema, which validate-schemas.mjs would already
+ * have failed on.
+ */
+const STATE_SCHEMA_VERSION = (() => {
+  try {
+    const schemaPath = new URL("../schemas/agent-state.schema.json", import.meta.url);
+    const sv = JSON.parse(readFileSync(schemaPath, "utf-8"))?.properties?.schemaVersion;
+    return sv?.const ?? sv?.enum?.at(-1) ?? "2.1.0";
+  } catch {
+    return "2.1.0";
+  }
+})();
+
 function deepMerge(base, patch) {
   if (Array.isArray(patch)) return patch; // arrays replace
   if (typeof patch !== "object" || patch === null) return patch;
@@ -236,7 +307,7 @@ function deepMerge(base, patch) {
 }
 
 async function main() {
-  const { replace, path } = parseArgs();
+  const { replace, path, ifRev } = parseArgs();
 
   // Read stdin
   const chunks = [];
@@ -257,7 +328,7 @@ async function main() {
   }
 
   try {
-    await acquireLock(path);
+    heldLockIno = await acquireLock(path);
     heldLockFor = path;
   } catch (err) {
     if (err.code === "LOCK_TIMEOUT") {
@@ -272,6 +343,8 @@ async function main() {
   // here must release OUR lock explicitly before exiting - otherwise a corrupt
   // state file (or any I/O error) leaks agent-state.json.lock and blocks the
   // next writer until the stale-lock window elapses.
+  const fileExistedBefore = existsSync(path);
+
   try {
     let next;
     if (replace) {
@@ -304,16 +377,67 @@ async function main() {
     // carries a `rev` from before the record moved, and following it down
     // would tell the next reader that nothing changed.
     let priorRev = Number.isInteger(next.rev) ? next.rev : 0;
+    let diskRev = null;
     if (existsSync(path)) {
       try {
         const parsed = JSON.parse(readFileSync(path, "utf-8"));
-        if (Number.isInteger(parsed?.rev)) priorRev = Math.max(priorRev, parsed.rev);
+        if (Number.isInteger(parsed?.rev)) {
+          diskRev = parsed.rev;
+          priorRev = Math.max(priorRev, parsed.rev);
+        }
       } catch {
         /* unreadable on disk - the merge path above already threw for that */
       }
     }
+
+    // Compare-and-swap. `rev` already told a reader whether the record moved;
+    // --if-rev is what lets it ACT on that instead of merging over the top.
+    //
+    // The lock closes the window between two writers. It does not close the
+    // one between a READ and a write, and `/multi-agent:steer` puts a second
+    // writer in exactly that window on purpose: it reads the state, a human
+    // thinks, and by the time the edit lands the run may have moved three
+    // phases. A merge then reinstates decisions the run already replaced.
+    //
+    // Refusing costs a re-read. Merging costs a phase that silently reverts.
+    if (ifRev !== null) {
+      const seen = diskRev ?? 0;
+      if (seen !== ifRev) {
+        console.error(
+          `write-state: rev is ${seen}, expected ${ifRev}  -  the record moved since you read it; re-read and retry`,
+        );
+        releaseLock(path);
+        process.exit(5);
+      }
+    }
+
     next.rev = priorRev + 1;
 
+    // schemaVersion is stamped only when this call CREATES the document. The
+    // migration runner keys on it, and a document that never carries one can
+    // never be migrated - measured on a real install, 43 of 43 state files had
+    // no schemaVersion, so pipeline/schemas/migrations/ was unreachable code.
+    // A merge into an existing unstamped file is deliberately left alone:
+    // stamping there would claim a conformance nothing verified.
+    if (!fileExistedBefore && typeof next.schemaVersion !== "string") {
+      next.schemaVersion = STATE_SCHEMA_VERSION;
+    }
+
+    // Last check before the write lands: is the lock still ours? Everything
+    // above read the file under a lock we believed we held, and if that belief
+    // stopped being true the rename would overwrite a concurrent writer's
+    // update with a merge that never saw it. Reporting success while losing an
+    // update is the one outcome this script exists to prevent, so it refuses
+    // instead - a caller that sees exit 4 can read and retry, which a caller
+    // that saw exit 0 never will.
+    if (!stillOurs(path, heldLockIno)) {
+      console.error(
+        `write-state: the lock was taken from us mid-write (${path}.lock). ` +
+          `Nothing was written. Re-read the state and retry.`,
+      );
+      process.exit(4);
+    }
+
     const tmp = `${dirname(path)}/.${basename(path)}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
     renameSync(tmp, path); // atomic on POSIX
@@ -327,8 +451,23 @@ async function main() {
   process.exit(0);
 }
 
-main().catch((err) => {
-  console.error(`write-state: unhandled  -  ${err.message}`);
-  if (heldLockFor) releaseLock(heldLockFor);
-  process.exit(3);
-});
+// Only run when invoked as a program. The lock helpers are the part with the
+// subtle behaviour and they are unreachable from a test otherwise: the window
+// they guard is microseconds wide, so a test that drives this file as a CLI
+// measures the scheduler rather than the code.
+const isDirectRun = invokedDirectly(import.meta.url);
+if (isDirectRun) {
+  // Exit 3 is this file's documented "died without writing" code, and the
+  // cleanup is the reason the handler exists at all: a writer that dies holding
+  // the advisory lock makes the NEXT writer wait out the acquire window and
+  // then decide, on nothing but age, whether to take a lock that may still be
+  // live. Releasing on the abnormal path keeps that decision from arising.
+  runMain("write-state", main, {
+    code: 3,
+    cleanup: () => {
+      if (heldLockFor) releaseLock(heldLockFor);
+    },
+  });
+}
+
+export { acquireLock, releaseLock, stillOurs, lockIdentityIfStale };