@mmerterden/multi-agent-pipeline 16.14.0 → 16.16.0

package/pipeline/scripts/gate-linux.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# gate-linux.sh  -  run the ci-lite job on a real Ubuntu image, locally.
+#
+# The pre-push gate (pre-push-check.sh) is the primary one, but it runs on the
+# maintainer's macOS workstation against an installed node_modules that has
+# accumulated over months. Two things it cannot answer: does this tree work on
+# Linux, and does `npm ci` from the lockfile into an empty tree still resolve.
+# ci-lite.yml answers both, and has not executed since 2026-07-25.
+#
+# `act` runs that workflow against the same image GitHub would use, so the
+# answer comes from the workflow definition rather than from a second script
+# that would drift away from it.
+#
+# NOT part of `npm run gate` on purpose: act and Docker are not installed
+# everywhere, and a required gate that cannot run is the failure ADR-0011
+# exists to avoid. Run it before a release, or after touching install/,
+# lib/credential-store.sh, or anything path-shaped.
+#
+# Needs network inside the container: the scorecard's dependency metrics ask
+# the registry (advisories and signatures) and report an unreachable registry
+# as a failure rather than a skip, on the grounds that a supply-chain check
+# which goes green without reaching the registry is worse than no check.
+#
+# Exit codes: 0 = the job passed, 1 = the job failed, 2 = tooling missing
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT" || { echo "FAIL: can't cd to repo root" >&2; exit 2; }
+
+if ! command -v act >/dev/null 2>&1; then
+  cat >&2 <<'MSG'
+✗ act is not installed - this gate needs it to run the Ubuntu job locally.
+
+    brew install act        # macOS
+    # and a running Docker daemon (Docker Desktop, colima, orbstack)
+
+Why this is not bundled: it pulls a multi-gigabyte runner image. The rest of
+the gate chain (npm run gate) has no such dependency and stays the default.
+MSG
+  exit 2
+fi
+
+if ! docker info >/dev/null 2>&1; then
+  echo "✗ act is installed but no Docker daemon is reachable. Start Docker and retry." >&2
+  exit 2
+fi
+
+echo "→ Running ci-lite on ubuntu-22.04 via act (this pulls an image on first run)"
+echo ""
+
+if act workflow_dispatch \
+  -W .github/workflows/ci-lite.yml \
+  -P ubuntu-latest=catthehacker/ubuntu:act-22.04; then
+  echo ""
+  echo "✓ ci-lite passed on Linux"
+  exit 0
+fi
+
+echo "" >&2
+echo "✗ ci-lite failed on Linux. A pass on macOS does not cover this." >&2
+exit 1

package/pipeline/scripts/localize-commands.mjs

@@ -116,8 +116,7 @@ export function localizeCommands(dir, mode) {
 // `.split("/").pop()` never split a backslash path, so on Windows this was
 // always false - `restore` exited 0 doing nothing and /multi-agent:sync then
 // mirrored localized descriptions into the repo, the one thing it must prevent.
-const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   const args = process.argv.slice(2);
   const mode = args[0];

package/pipeline/scripts/pre-push-check.sh

@@ -3,10 +3,12 @@
 #
 # Purpose:
 #   The repo HAS workflows (test.yml, ci-lite.yml), but they have not executed
-#   since 2026-07-25: the jobs complete in ~2 seconds with zero steps recorded,
-#   which is a runner/quota block rather than a test failure. Until that is
-#   resolved, this hook is not a second opinion - it is the only thing standing
-#   between a broken commit and npm.
+#   since 2026-07-02: every attempt after that day - the last on 2026-07-25 -
+#   finished in about four seconds with zero steps recorded, which is a
+#   runner/quota block rather than a test failure. Both are now dormant by
+#   declaration too (ADR-0011: the push triggers are commented out). So this
+#   hook is not a second opinion - it is the only thing standing between a
+#   broken commit and npm.
 #
 #   It therefore runs the CANONICAL chain, `npm test`, rather than a hand-picked
 #   subset. The subset it used to run was missing eight of the eleven steps

package/pipeline/scripts/usage-report.mjs

@@ -69,8 +69,7 @@ function readJson(path) {
 
 function resolveGlobalPrefs() {
   const path =
-    process.env.MULTI_AGENT_PREFS ||
-    join(homedir(), ".claude", "multi-agent-preferences.json");
+    process.env.MULTI_AGENT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json");
   return readJson(path)?.global ?? {};
 }
 
@@ -130,9 +129,7 @@ function enabledPlugins(state) {
   ]) {
     for (const name of readEnabledPluginNames(s)) names.add(name.split("@")[0]);
   }
-  return Array.from(names)
-    .filter(Boolean)
-    .slice(0, 20);
+  return Array.from(names).filter(Boolean).slice(0, 20);
 }
 
 function integrationTags(state) {
@@ -146,8 +143,7 @@ function integrationTags(state) {
     const tool = String(call?.tool || "");
     // Server segment may contain hyphens (mcp__multi-agent-toolkit__ios_tap), so the
     // class must accept them or "multi-agent-toolkit" collapses to "dev".
-    const m =
-      tool.match(/^mcp__([a-z0-9_-]+?)__/i) || tool.match(/^mcp__([a-z0-9_-]+)/i);
+    const m = tool.match(/^mcp__([a-z0-9_-]+?)__/i) || tool.match(/^mcp__([a-z0-9_-]+)/i);
     if (m) apps.add(m[1].replace(/_/g, "-").toLowerCase());
   }
   return Array.from(apps).slice(0, 20);
@@ -345,7 +341,8 @@ function trackerSummary(state) {
   const phs = [];
   const failed = [];
   const models = new Set();
-  let startedAt = typeof tracker?.started_at === "string" && tracker.started_at ? tracker.started_at : null;
+  let startedAt =
+    typeof tracker?.started_at === "string" && tracker.started_at ? tracker.started_at : null;
   let endedAt = null;
   for (const p of list) {
     const id = p?.id != null && String(p.id) !== "" ? String(p.id) : "?";
@@ -510,9 +507,7 @@ function buildEvent(state) {
     ph: typeof state.currentPhase === "number" ? state.currentPhase : null,
     st: state.status || null,
     hr: state.haltReason || null,
-    ri: Array.isArray(state.reviewIterations)
-      ? state.reviewIterations.length
-      : 0,
+    ri: Array.isArray(state.reviewIterations) ? state.reviewIterations.length : 0,
     pr: Boolean(state.pr && (state.pr.url || state.pr.number)),
     du: durationSec(state, spend),
     tk: spend.tk,
@@ -612,10 +607,17 @@ async function main() {
 }
 
 // Windows-safe entry-point check: compare file URLs, never string-split a path.
-const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   main().catch(() => process.exit(0));
 }
 
-export { endpointAllowed, integrationTags, enabledPlugins, readEnabledPluginNames, trackerSummary, buildEvent, resolveUser };
+export {
+  endpointAllowed,
+  integrationTags,
+  enabledPlugins,
+  readEnabledPluginNames,
+  trackerSummary,
+  buildEvent,
+  resolveUser,
+};

package/pipeline/scripts/validate-analysis-doc.mjs

@@ -46,9 +46,7 @@ import { readFileSync } from "node:fs";
 // "mobile" and "web" are its platform values. "none" is the narrower case where the
 // evidence describes no interface at all. All three are real values, not missing ones.
 // "web" is the pre-"web" spelling, still accepted so older documents validate.
-const KNOWN_PLATFORMS = new Set([
-  "ios", "android", "web", "backend", "mobile", "frontend", "none",
-]);
+const KNOWN_PLATFORMS = new Set(["ios", "android", "web", "backend", "mobile", "frontend", "none"]);
 const REQUIRED_FM = ["feature", "platform", "language", "mode", "template_version"];
 
 // Never-omitted sections (Locked 2), matched by bilingual title keyword so the
@@ -70,13 +68,19 @@ const REQUIRED_SECTIONS = [
 const CORPORATE_SECTIONS = [
   { key: "purpose and scope", any: ["Amaç ve Kapsam", "Amac ve Kapsam", "Purpose and Scope"] },
   { key: "business analysis", any: ["İş Analizi", "Is Analizi", "Business Analysis"] },
-  { key: "business requirements", any: ["İş Gereksinimleri", "Is Gereksinimleri", "Business Requirements"] },
+  {
+    key: "business requirements",
+    any: ["İş Gereksinimleri", "Is Gereksinimleri", "Business Requirements"],
+  },
   { key: "ai requirements", any: ["Yapay Zeka", "AI Requirements"] },
   { key: "use cases", any: ["Kullanım Senaryoları", "Kullanim Senaryolari", "Use Cases"] },
   { key: "hardware and infrastructure", any: ["Donanım", "Donanim", "Hardware"] },
   { key: "quality requirements", any: ["Kalite Gereksinimleri", "Quality Requirements"] },
   { key: "regulatory requirements", any: ["Regülasyonel", "Regulasyonel", "Regulatory"] },
-  { key: "content requirements", any: ["İçerik Gereksinimleri", "Icerik Gereksinimleri", "Content Requirements"] },
+  {
+    key: "content requirements",
+    any: ["İçerik Gereksinimleri", "Icerik Gereksinimleri", "Content Requirements"],
+  },
   { key: "risks", any: ["Riskler", "Risks"] },
   { key: "references", any: ["Referanslar", "References"] },
 ];
@@ -226,9 +230,7 @@ function main() {
   // defines AS-07, and each side is checked against the other.
   if (profile === "corporate") {
     const lines = text.split("\n");
-    const risksStart = lines.findIndex((l) =>
-      /^#{2,3}\s+\d+/.test(l) && /(Riskler|Risks)/.test(l),
-    );
+    const risksStart = lines.findIndex((l) => /^#{2,3}\s+\d+/.test(l) && /(Riskler|Risks)/.test(l));
     let risksBlock = "";
     if (risksStart !== -1) {
       for (let i = risksStart + 1; i < lines.length; i++) {
@@ -237,9 +239,7 @@ function main() {
       }
     }
     const AS_ID = /\bAS-(\d{2,3})\b/g;
-    const definedIds = new Set(
-      [...risksBlock.matchAll(AS_ID)].map((m) => `AS-${m[1]}`),
-    );
+    const definedIds = new Set([...risksBlock.matchAll(AS_ID)].map((m) => `AS-${m[1]}`));
     const referencedIds = new Set();
     for (let i = 0; i < lines.length; i++) {
       if (risksStart !== -1 && i > risksStart) continue;
@@ -248,9 +248,7 @@ function main() {
       // A gap that names no id cannot be traced to an owner, which is the whole
       // point of admitting it.
       if (!/\bAS-\d{2,3}\b/.test(lines[i])) {
-        errors.push(
-          `line ${i + 1}: EKLENECEK carries no AS-NN reference (Locked 33)`,
-        );
+        errors.push(`line ${i + 1}: EKLENECEK carries no AS-NN reference (Locked 33)`);
       }
     }
     for (const id of referencedIds) {
@@ -264,9 +262,7 @@ function main() {
       if (!referencedIds.has(id)) {
         // An open question with no body reference is allowed only when the row
         // says so; otherwise it is a question about nothing the document raises.
-        const row = risksBlock
-          .split("\n")
-          .find((l) => l.includes(id)) || "";
+        const row = risksBlock.split("\n").find((l) => l.includes(id)) || "";
         if (!/(no body reference|govde referansi yok)/i.test(row)) {
           errors.push(
             `${id} is defined in Risks and Open Questions but never referenced in the body (Locked 33)`,
@@ -318,7 +314,9 @@ function main() {
 
           for (const id of defined) {
             if (!inMatrix.has(id)) {
-              errors.push(`${id} is defined in the document but missing from the traceability matrix`);
+              errors.push(
+                `${id} is defined in the document but missing from the traceability matrix`,
+              );
             }
           }
           for (const id of inMatrix) {
@@ -342,12 +340,23 @@ function main() {
     let inMermaid = false;
     for (let i = 0; i < mmLines.length; i++) {
       const t = mmLines[i].trim();
-      if (/^```mermaid\s*$/.test(t)) { inMermaid = true; continue; }
-      if (inMermaid && t === "```") { inMermaid = false; continue; }
+      if (/^```mermaid\s*$/.test(t)) {
+        inMermaid = true;
+        continue;
+      }
+      if (inMermaid && t === "```") {
+        inMermaid = false;
+        continue;
+      }
       if (!inMermaid) continue;
       const labels = [...mmLines[i].matchAll(/[[({|]([^\]})|]{3,})[\]})|]/g)].map((m) => m[1]);
       for (const lbl of labels) {
-        if (/^[\x20-\x7E]+$/.test(lbl) && /\b(Hayir|Basarili|Basarisiz|Odeme|Iptal|Gecerli|Gecersiz|Secim|Dogrulama|Uyari|Baslangic|Bitis|Onay|Aciklama)\b/.test(lbl)) {
+        if (
+          /^[\x20-\x7E]+$/.test(lbl) &&
+          /\b(Hayir|Basarili|Basarisiz|Odeme|Iptal|Gecerli|Gecersiz|Secim|Dogrulama|Uyari|Baslangic|Bitis|Onay|Aciklama)\b/.test(
+            lbl,
+          )
+        ) {
           errors.push(
             `WARN line ${i + 1}: diagram label "${lbl}" looks like Turkish flattened to ASCII (Locked 7)`,
           );
@@ -356,7 +365,6 @@ function main() {
     }
   }
 
-
   // 2b. Opt-in coverage sections must be present when the front-matter says so.
   const uiTests = String(parsed?.fm?.ui_tests || "false").toLowerCase() === "true";
   const a11yDepth = String(parsed?.fm?.a11y_depth || "basic").toLowerCase();
@@ -402,7 +410,9 @@ function main() {
       if (parsed?.fm?.platform === "backend") {
         warns.push(`${msg} - allowed for backend only when no contract testing is planned`);
       } else {
-        errors.push(`missing Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 31)`);
+        errors.push(
+          `missing Section 15 Test Plan; Full mode dev reads it as the RED input (Locked 31)`,
+        );
       }
     } else {
       const hasUnit =
@@ -469,7 +479,11 @@ function main() {
   // The pre-existing occurrence-count heuristic below stays as the looser net.
   if (mode === "full") {
     const idRx = /BR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/gi;
-    const storyBody = sectionBody(allLines, ["Kullanıcı Hikayeleri", "Kullanici Hikayeleri", "User Stories"]);
+    const storyBody = sectionBody(allLines, [
+      "Kullanıcı Hikayeleri",
+      "Kullanici Hikayeleri",
+      "User Stories",
+    ]);
     const testBody = sectionBody(allLines, ["Test Planı", "Test Plani", "Test Plan"]);
     if (storyBody && testBody) {
       const defined = new Set((storyBody.join("\n").match(idRx) || []).map((x) => x.toUpperCase()));
@@ -556,13 +570,18 @@ function main() {
       inVariant = true;
       continue;
     }
-    if (inVariant && /^#{1,3}\s/.test(line)) { inVariant = false; continue; }
+    if (inVariant && /^#{1,3}\s/.test(line)) {
+      inVariant = false;
+      continue;
+    }
     if (!inVariant || !/^\|/.test(line)) continue;
     const cells = line.split("|").map((c) => c.trim());
-    if (cells.length < 7) continue;                      // not the 6-column body
+    if (cells.length < 7) continue; // not the 6-column body
     if (/^-+$/.test(cells[1]) || /Bile\u015fen|Component/i.test(cells[1])) continue;
     if (!cells[3] || !cells[4]) {
-      errors.push(`variant row "${cells[1]}" is missing the all-values or used-here column (Section 6.X / Locked 29)`);
+      errors.push(
+        `variant row "${cells[1]}" is missing the all-values or used-here column (Section 6.X / Locked 29)`,
+      );
     }
   }
 

package/pipeline/scripts/validate-analysis.mjs

@@ -21,7 +21,13 @@ import { readFileSync } from "node:fs";
 // output, a golden-task fixture or a resumed run written before the rename still
 // validates; new output uses "web". Mirrors analysis-output.schema.json.
 const ALLOWED_STACKS = new Set([
-  "ios", "android", "backend", "web", "mobile", "frontend", "unknown",
+  "ios",
+  "android",
+  "backend",
+  "web",
+  "mobile",
+  "frontend",
+  "unknown",
 ]);
 const ALLOWED_SEVERITIES = new Set(["low", "medium", "high"]);
 

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -46,14 +46,18 @@ const REQUIRED_FM = ["run_name", "generated_at", "language", "complaint_count",
 const REQUIRED_SECTIONS = [
   { key: "summary", any: ["Summary", "Özet", "Ozet"] },
   { key: "triage table", any: ["Triage"] },
-  { key: "complaint details", any: ["Complaint Details", "Şikayet Detayları", "Sikayet Detaylari", "Detay"] },
+  {
+    key: "complaint details",
+    any: ["Complaint Details", "Şikayet Detayları", "Sikayet Detaylari", "Detay"],
+  },
   { key: "open questions", any: ["Open Questions", "Açık Sorular", "Acik Sorular"] },
   { key: "methodology", any: ["Methodology", "Metodoloji"] },
   { key: "references", any: ["References", "Referanslar"] },
 ];
 
 const ROUTING_KEYWORDS = ["Routing", "Yönlendirme", "Yonlendirme"];
-const FIX_PLAN_RE = /(Fix plan|Fix Plan|Geliştirme planı|Geliştirme Planı|Gelistirme plani|Gelistirme Plani)/;
+const FIX_PLAN_RE =
+  /(Fix plan|Fix Plan|Geliştirme planı|Geliştirme Planı|Gelistirme plani|Gelistirme Plani)/;
 
 // Cell-exact on purpose: a substring match would classify a row as `core`
 // because its summary says "core-data" or "core team" before the verdict column.
@@ -164,7 +168,9 @@ function main() {
   const triageScope = sectionBody(text, ["Triage"]) ?? text;
   const rows = triageScope.split("\n").filter((l) => /^\s*\|\s*C-\d{2,}\s*\|/.test(l));
   if (rows.length === 0) {
-    errors.push("no triage rows found (expected Triage-section rows with a C-NN id in the first cell)");
+    errors.push(
+      "no triage rows found (expected Triage-section rows with a C-NN id in the first cell)",
+    );
   }
   const coreIds = [];
   const handoffIds = [];
@@ -173,7 +179,9 @@ function main() {
     const cells = row.split("|").map((c) => c.trim());
     const verdict = cells.find((c) => VERDICT_CELL_RE.test(c));
     if (!verdict) {
-      errors.push(`triage row ${id} has no valid verdict token (client:<layer> | bff:<layer> | core | insufficient-evidence)`);
+      errors.push(
+        `triage row ${id} has no valid verdict token (client:<layer> | bff:<layer> | core | insufficient-evidence)`,
+      );
     } else if (verdict === "core" && !coreIds.includes(id)) {
       coreIds.push(id);
     } else if (/^(client|bff):/.test(verdict) && !handoffIds.includes(id)) {
@@ -185,7 +193,9 @@ function main() {
   if (coreIds.length > 0) {
     const routing = sectionBody(text, ROUTING_KEYWORDS);
     if (!routing) {
-      errors.push(`core verdict(s) ${coreIds.join(", ")} but no routing section (Yönlendirme / Routing)`);
+      errors.push(
+        `core verdict(s) ${coreIds.join(", ")} but no routing section (Yönlendirme / Routing)`,
+      );
     } else {
       for (const id of coreIds) {
         if (!routing.includes(id)) {
@@ -200,7 +210,9 @@ function main() {
   for (const id of handoffIds) {
     const detail = sectionBody(text, [id]);
     if (!detail || !FIX_PLAN_RE.test(detail)) {
-      errors.push(`client/bff verdict ${id} has no fix-plan block (Fix plan / Geliştirme planı) in its detail section`);
+      errors.push(
+        `client/bff verdict ${id} has no fix-plan block (Fix plan / Geliştirme planı) in its detail section`,
+      );
     }
   }
 
@@ -223,10 +235,14 @@ function main() {
       errors.push(`redaction leak: card-like digit run at line ${i + 1}`);
     }
     if (NATIONAL_ID_RE.test(bodyLines[i]) && !CARD_RE.test(bodyLines[i])) {
-      warns.push(`possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`);
+      warns.push(
+        `possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`,
+      );
     }
     if (PNR_MIXED_RE.test(bodyLines[i]) || PNR_CONTEXT_RE.test(bodyLines[i])) {
-      warns.push(`possible redaction leak: PNR-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`);
+      warns.push(
+        `possible redaction leak: PNR-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`,
+      );
     }
   }
 

package/pipeline/scripts/write-state.mjs

@@ -25,8 +25,20 @@
  *
  * Tunables (env):
  *   WRITE_STATE_LOCK_TIMEOUT_MS  acquire window before exit 2 (default 15000)
- *   WRITE_STATE_LOCK_STALE_MS    age past which a lock is reclaimed (default 30000)
- * A dead holder (PID no longer alive) is reclaimed immediately regardless of age.
+ *   WRITE_STATE_LOCK_STALE_MS    age past which a lock with no readable PID is
+ *                                reclaimed (default 30000)
+ *   WRITE_STATE_LOCK_ABANDON_MS  ceiling past which even a lock that probes as
+ *                                alive is reclaimed, covering PID reuse
+ *                                (default: 10x STALE_MS)
+ * A dead holder (PID no longer alive) is reclaimed immediately regardless of
+ * age. A live holder keeps its lock: liveness outranks age. See
+ * lockIdentityIfStale() for why that order is load-bearing.
+ *
+ * Every successful write bumps `rev`, a counter that only ever increases. A
+ * reader that kept the `rev` it read can tell whether the record moved under
+ * it before writing back. The lock makes a single write atomic; it does not
+ * cover the gap between a phase reading state and writing it back, and
+ * `/multi-agent:steer` puts a deliberate second writer in that gap.
  */
 
 import {
@@ -136,11 +148,29 @@ async function acquireLock(
 }
 
 /**
- * A lock is stale when its owning PID is no longer alive, or when the lock
- * file is older than `staleMs` (which also covers PID reuse).
+ * A lock is stale when its owning PID is no longer alive. Age alone is not
+ * staleness.
+ *
+ * The order here is the whole point. Age used to be checked first and returned
+ * "stale" on its own, so a holder that was demonstrably ALIVE lost its lock the
+ * moment the file passed 30 seconds - and the next writer then deleted a live
+ * lock and overwrote the update behind it. Liveness is direct evidence;
+ * a timestamp is a guess about it, and a guess must not overrule the evidence.
+ *
+ * Age survives for the one case liveness cannot answer: PID reuse. A dead
+ * holder whose PID has been recycled by an unrelated process probes as alive
+ * forever, so a lock that is alive but older than `abandonMs` is reclaimed
+ * anyway. That ceiling is deliberately far above any real write (default ten
+ * times `staleMs`), because it is a last resort rather than a routine path.
+ *
+ * No periodic heartbeat: this writer holds the lock across one synchronous
+ * write and rename, so there is no window in which a timer could refresh the
+ * file - and refreshing a timestamp would be weaker evidence than the liveness
+ * probe already gives.
+ *
  * @param {string} lockPath
  * @param {number} staleMs
- * @returns {boolean}
+ * @returns {{ino: number, mtimeMs: number} | null}
  */
 function lockIdentityIfStale(lockPath, staleMs) {
   let pid;
@@ -156,13 +186,17 @@ function lockIdentityIfStale(lockPath, staleMs) {
     return null;
   }
   const identity = { ino, mtimeMs };
-  if (Date.now() - mtimeMs > staleMs) return identity;
-  // An unreadable PID is NOT proof of staleness. Treating it as such is what
-  // let a writer delete a live lock and lose another writer's update. With the
-  // link-based acquire above a lock is never observable without its PID, so
-  // this can only be genuine corruption - which the staleMs check reclaims
-  // anyway, without racing a writer that is merely mid-flight.
-  if (!Number.isInteger(pid) || pid <= 0) return null;
+  const abandonMs = Number(process.env.WRITE_STATE_LOCK_ABANDON_MS) || staleMs * 10;
+  const age = Date.now() - mtimeMs;
+
+  // PID-reuse ceiling. Only reached by a lock that still probes as alive after
+  // a length of time no legitimate write comes close to.
+  if (age > abandonMs) return identity;
+
+  // A lock with no readable PID cannot be probed, so age is the only evidence
+  // left for it. That is corruption rather than a live writer: the link-based
+  // acquire makes a lock observable only after its PID is inside.
+  if (!Number.isInteger(pid) || pid <= 0) return age > staleMs ? identity : null;
   try {
     process.kill(pid, 0); // probe liveness without signalling
     return null; // holder alive
@@ -255,6 +289,31 @@ async function main() {
       next = deepMerge(current, payload);
     }
 
+    // A state document is an object. Anything else cannot carry `rev`, and
+    // assigning to a primitive throws a raw TypeError from inside the writer,
+    // which is a worse answer than saying so. `--replace` is where this
+    // reaches: the merge path can only ever produce an object.
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      throw new Error(
+        `state must be a JSON object, got ${Array.isArray(next) ? "array" : typeof next}`,
+      );
+    }
+
+    // Monotonic revision, taken as the HIGHER of what the incoming document
+    // carries and what is on disk. A reader that writes back what it read
+    // 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;
+    if (existsSync(path)) {
+      try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (Number.isInteger(parsed?.rev)) priorRev = Math.max(priorRev, parsed.rev);
+      } catch {
+        /* unreadable on disk - the merge path above already threw for that */
+      }
+    }
+    next.rev = priorRev + 1;
+
     const tmp = `${dirname(path)}/.${basename(path)}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
     renameSync(tmp, path); // atomic on POSIX

package/pipeline/skills/shared/core/multi-agent-steer/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: multi-agent-steer
+language: en
+description: "Queue an instruction for a task that is already running. It is applied at the next phase boundary, not mid-phase. Use when a run is going the wrong way and killing it would throw away good work."
+user-invocable: true
+argument-hint: "#id \"<instruction>\"  -  e.g. #3 \"the field is called web, not frontend\". With no instruction, you are asked for it."
+---
+
+# multi-agent steer  -  correct a run without stopping it
+
+**Input**: $ARGUMENTS
+
+Leave one instruction for a running task. The next phase reads it before it
+starts work, applies it, and marks it consumed.
+
+This exists because the alternative was losing the run. `kill` stops a task and
+deletes its worktree; `resume` picks a stopped one back up. Neither helps while
+a phase is in flight, so a correction that arrived mid-run - "that field is
+called `web`, not `frontend`", "keep the analysis, drop the rest" - had nowhere
+to go, and the run carried on in the wrong direction until it finished.
+
+**Not a second prompt.** One instruction is queued at a time. Steering a task
+that already has an unconsumed instruction replaces it, after showing you what
+is being replaced.
+
+## Steps
+
+1. **Find the task**  -  parse `#N` or `{JIRA-KEY}-XXXXX` from the argument,
+   the same way `kill` and `resume` do. Locate its `agent-state.json`:
+
+   ```bash
+   find {repo}/.worktrees/ -name "agent-state.json" -maxdepth 2
+   find $HOME/.claude/logs/multi-agent -maxdepth 4 -name agent-state.json -path '*/artifacts/*'
+   ```
+
+   Not found → `ERR: no task #N. '/multi-agent:status' lists what is running.`
+
+2. **Check it can still be steered**  -  read `status` and `currentPhase`:
+
+   | State | What to do |
+   |---|---|
+   | `in_progress` | Queue it. This is the case the command is for. |
+   | `paused` / `failed` | Say the task is not running, and that `/multi-agent:resume #N` will re-enter with the instruction applied at that phase's entry. Queue it. |
+   | `complete` | Refuse. Nothing will read it. Point at `/multi-agent` for a follow-up run. |
+
+   `currentPhase` is 7 and status is `in_progress` → warn that Phase 7 is the
+   last one, so an instruction queued now may never be consumed.
+
+3. **Read the instruction**  -  from the argument, or ask for it when the
+   argument carries only an id. Verbatim, up to 4000 characters. Do not
+   summarize or rewrite it: the phase that consumes it needs the user's own
+   words, and a paraphrase is where the meaning goes.
+
+4. **Show what will be queued, and ask**:
+
+   ```
+   Steer #3 ({JIRA-KEY}-12345, Phase 3 Dev, in_progress)
+
+     "the field is called web, not frontend"
+
+   Applied at the entry to Phase 4. The current phase finishes as it is.
+   ```
+
+   Already carrying an unconsumed `pendingSteer` → print the old text above the
+   new one and ask whether to replace it.
+
+5. **Write it**  -  through the state writer, never by editing the file, because
+   the running task is writing to it too. `$STATE_FILE` is the path from step 1
+   and `$INSTRUCTION` the text from step 3:
+
+   ```bash
+   printf '{"pendingSteer":{"text":%s,"at":"%s","appliedAt":null,"appliedPhase":null}}' \
+     "$(node -e 'process.stdout.write(JSON.stringify(process.argv[1]))' "$INSTRUCTION")" \
+     "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+     | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+   ```
+
+   The instruction is JSON-encoded by `node -e`, not by hand: it is arbitrary
+   user text, and a quote or newline in it would otherwise produce invalid JSON
+   or, worse, a payload that merges into fields nobody meant to touch.
+
+   Exit 2 (lock timeout) → the task is mid-write. Retry once, then report it
+   rather than forcing the write.
+
+6. **Confirm**: `🧭 Steer queued for #N  -  applies at the entry to Phase {N+1}`
+
+## What the phase does with it
+
+Phase entry, before any work: read a `pendingSteer` that has no `appliedAt`.
+When present, apply it to that phase's context, set `appliedAt` and
+`appliedPhase` - which is what stops it being read a second time - and write a
+`Steer applied` line into `agent-log.md`. The record itself stays, so the run
+keeps the trace of what was asked and when. The contract lives in
+`$HOME/.claude/multi-agent-refs/phases.md` under "Phase entry  -  pending
+steer" (the file has a second, unrelated "Phase entry" line inside the tracker
+block).
+
+Applied at entry rather than the moment it arrives, on purpose: a phase that
+changes target halfway through throws away the work it already did, which is
+the outcome this command exists to avoid.
+
+An instruction that contradicts the plan is not silently obeyed. The phase says
+what it is changing, and a contradiction that would invalidate an approved plan
+halts for the user instead of quietly rewriting it.
+
+**One limit worth knowing.** The reader is the phase contract, so a task started
+by an install that predates it will not consume the field: the instruction is
+written and nothing picks it up. There is no version stamp on a state file to
+detect this from, so the honest advice is that steer applies to runs started
+after the install carrying it. A run already in flight from an older install is
+still a `kill` or a wait.