@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/process-tree.mjs

@@ -0,0 +1,161 @@
+// Best-effort process-tree cleanup shared by the gate runner and tests.
+// Zero dependencies. Node 16+.
+
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { win32 } from "node:path";
+
+export const WINDOWS_TASKKILL_TIMEOUT_MS = 1000;
+
+export function windowsTaskkillPath(env = process.env) {
+  const normalizeRoot = (value) => String(value || "").replace(/\//g, "\\").replace(/\\+$/, "");
+  const systemRoot = normalizeRoot(env.SystemRoot);
+  const windir = normalizeRoot(env.WINDIR);
+  const systemDrive = String(env.SystemDrive || "").replace(/[\\/]+$/, "").toUpperCase();
+  const driveRoot = /^[A-Za-z]:\\Windows$/i;
+  // Require the three standard Windows launcher values to identify the same
+  // drive-root directory. A single arbitrary absolute variable must not select
+  // an executable, and disagreement fails closed to the ChildProcess handle.
+  if (driveRoot.test(systemRoot) && driveRoot.test(windir) &&
+      systemRoot.toLowerCase() === windir.toLowerCase() &&
+      systemDrive === systemRoot.slice(0, 2).toUpperCase()) {
+    return win32.join(systemRoot, "System32", "taskkill.exe");
+  }
+  // A bare executable name consults cwd/PATH, which are controlled by the
+  // CHECK environment. If neither trusted system root exists, skip the helper
+  // and use the already-held ChildProcess handle instead.
+  return null;
+}
+
+function syncFailure(result) {
+  if (!result) return "returned no result";
+  if (result.error) return result.error.code || result.error.message || "spawn error";
+  if (result.signal) return "signal " + result.signal;
+  if (result.status !== 0) return "exit " + String(result.status);
+  return null;
+}
+
+const childExited = (child) => child.exitCode !== null && child.exitCode !== undefined ||
+  child.signalCode !== null && child.signalCode !== undefined;
+
+export function terminateProcessTree(child, options = {}) {
+  const platform = options.platform || process.platform;
+  const spawnSyncImpl = options.spawnSyncImpl || nodeSpawnSync;
+  const killGroup = options.killGroup || process.kill;
+  const pid = child && child.pid;
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { ok: false, fallback: false, diagnostic: "child PID is unavailable" };
+  }
+
+  if (platform !== "win32") {
+    // The gate runner launches a detached Node supervisor as the group leader
+    // and keeps it alive until the shell and inherited stdout/stderr close. If
+    // Node has already observed that supervisor exit, the numeric PGID no
+    // longer carries identity and may have been reused; never signal it.
+    if (childExited(child)) {
+      return { ok: true, fallback: false, diagnostic: "process supervisor already exited" };
+    }
+    try {
+      killGroup(-pid, "SIGKILL");
+      return { ok: true, fallback: false, diagnostic: null };
+    } catch (error) {
+      if (childExited(child)) {
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); supervisor already exited",
+        };
+      }
+      try {
+        const requested = child.kill("SIGKILL");
+        if (requested === false) {
+          return {
+            ok: false,
+            fallback: true,
+            diagnostic: "process-group kill failed (" + (error.code || error.message) +
+              "); child fallback returned false",
+          };
+        }
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); child fallback requested",
+        };
+      } catch (fallbackError) {
+        return {
+          ok: false,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) +
+            "); child fallback failed (" + (fallbackError.code || fallbackError.message) + ")",
+        };
+      }
+    }
+  }
+
+  // taskkill addresses the stored leader PID, unlike a POSIX process-group
+  // request. Do not target it after Node reports exit because the PID may have
+  // been reused while an inherited pipe remains open.
+  if (childExited(child)) {
+    return { ok: true, fallback: false, diagnostic: "child already exited" };
+  }
+
+  const command = windowsTaskkillPath(options.env || process.env);
+  const requestedTimeout = Number(options.taskkillTimeoutMs);
+  const taskkillTimeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+    ? Math.floor(requestedTimeout)
+    : WINDOWS_TASKKILL_TIMEOUT_MS;
+  let result;
+  let failure;
+  if (!command) {
+    failure = "trusted system taskkill path unavailable";
+  } else {
+    try {
+      result = spawnSyncImpl(command, ["/pid", String(pid), "/f", "/t"], {
+        stdio: "ignore",
+        windowsHide: true,
+        // Cleanup runs inside the gate timeout path. A broken helper must not
+        // replace a bounded CHECK with an unbounded synchronous wait.
+        timeout: taskkillTimeoutMs,
+        killSignal: "SIGKILL",
+      });
+      failure = syncFailure(result);
+    } catch (error) {
+      failure = error.code || error.message || "spawn threw";
+    }
+  }
+  if (!failure) return { ok: true, fallback: false, diagnostic: null, command };
+
+  if (childExited(child)) {
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child already exited",
+    };
+  }
+
+  try {
+    const requested = child.kill("SIGKILL");
+    if (requested === false) {
+      return {
+        ok: false,
+        fallback: true,
+        command,
+        diagnostic: "taskkill failed (" + failure + "); child fallback returned false",
+      };
+    }
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback requested",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback failed (" +
+        (error.code || error.message) + ")",
+    };
+  }
+}

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/regex-worker.mjs

@@ -0,0 +1,9 @@
+import { parentPort } from "node:worker_threads";
+
+parentPort.once("message", ({ source, flags, output }) => {
+  try {
+    parentPort.postMessage({ matched: new RegExp(source, flags).test(output) });
+  } catch (error) {
+    parentPort.postMessage({ error: error.message });
+  }
+});

package/plugins/maestro-skills/vendor/unlazy/templates/PLAN.md

@@ -0,0 +1,116 @@
+# Plan: <task>
+
+Scope: <validated pipeline id; store this file at .unlazy/<scope>/PLAN.md>
+Depth: tree <N>
+Mode: orchestrated
+
+## Contract
+
+Decide before fan-out:
+
+- Interfaces: <signatures, schemas, formats, integration points>
+- Ownership: <one complete set of repository-relative paths per leaf; no absolute paths, traversal, or concurrent overlap>
+- Dependencies: <leaf ids that must be VERIFIED first>
+- Host launch mode: <Codex native subagents | Claude background Agents | Claude Dynamic Workflow | sequential fallback>
+- Wave policy: <which independent READY leaves launch together and the maximum host concurrency>
+- Toolchain: <runtime versions, shell, working-directory rules, test commands>
+- Conventions: <naming, errors, compatibility, formatting>
+- Manual review: <owner and evidence standard for consequential manual gates>
+
+## Current contract inventory
+
+Contract revision: 1. Before fan-out, reread the original request and current amendments. Record every independently omittable required outcome and every constraint that changes acceptance; do not copy credentials, private text, or unrelated context.
+
+| ID | Required outcome or constraint | Owner | Observing gate or manual review | Disposition | Revision |
+|---|---|---|---|---|---|
+| C1 | <concise paraphrase> | <leaf/node> | <qualified gate/reviewer> | ACTIVE | 1 |
+
+Use stable ids. On an amendment, increment the revision and reconcile every affected row before dispatch or completion credit. `ACTIVE` is complete only with a current owner and observation. `ABANDONED`, `DEFERRED`, and `OWNER_DECISION` are honest non-completion; only explicit user authority may use `REMOVED_BY_USER`.
+
+## State vocabulary
+
+Leaf state is exactly one of:
+
+- WAITING: at least one id in Needs is not VERIFIED
+- READY: dependencies are VERIFIED and ownership can be claimed
+- IN-FLIGHT: dispatched, not yet parent-verified
+- VERIFIED: parent --reverify passed and manual gates were reviewed
+- ABANDONED: a required gate has a visible handoff
+
+Branch state is exactly one of OPEN, VERIFIED, or ABANDONED. Derive root and
+branch state from their ledgers; do not copy it into the topology tree.
+
+## Tree
+
+Use this tree only for parent-child topology and ledger paths. Use `leaf-` paths
+for work leaves and `node-` paths for branch integration. Keep leaf operational
+fields only in the dispatch table below; do not repeat `Owns`, `Needs`, `Tier`,
+`Planned wave`, or `State` here and do not create a separate schedule.
+
+- 1 <task> .............. GATES.md
+  - 1.1 <branch> ........ gates/node-1.1.md
+    - 1.1.1 <leaf> ...... gates/leaf-1.1.1.md
+    - 1.1.2 <leaf> ...... gates/leaf-1.1.2.md
+  - 1.2 <branch> ........ gates/node-1.2.md
+    - 1.2.1 <leaf> ...... gates/leaf-1.2.1.md
+    - 1.2.2 <leaf> ...... gates/leaf-1.2.2.md
+
+## Leaf dispatch table
+
+This is the single authoritative PLAN table for leaf operation. It is
+authoritative for `Needs`, `Tier`, `Planned wave`, and `State`; `Owns` remains
+visible here as the derived planning mirror described below. Keep exactly one
+row per tree leaf and do not duplicate these fields in the tree or a schedule.
+
+| Leaf | Owns | Needs | Tier | Planned wave | State |
+|---|---|---|---|---|---|
+| 1.1.1 | src/<a>/**, tests/<a>/** | - | mechanical | 1 | READY |
+| 1.1.2 | src/<b>/**, tests/<b>/** | - | judgment | 1 | READY |
+| 1.2.1 | src/<c>/**, tests/<c>/** | - | mechanical | 1 | READY |
+| 1.2.2 | src/<d>/**, tests/<d>/** | 1.2.1 | judgment | 2 | WAITING |
+
+`Owns` is a derived planning mirror of the complete glob set in the leaf ledger.
+The ledger's `OWNS:` header is the command-time authority read by `--claim`.
+Normalize both into sets and require equality before marking the row `READY` and
+again before each claim. On disagreement, fail closed, correct and log the plan
+or ledger, and recheck; never guess ownership. A successful claim does not prove
+the mirror agreed with the ledger.
+
+`Tier` is planner metadata for execution leaves. Use `judgment` when a leaf's own
+artifact needs design or review, and `mechanical` only when its pattern and gates
+are fixed. Map a tier through documented host-specific model or reasoning
+controls only when the host exposes them. Otherwise retain the tier as a briefing
+and review requirement without claiming a model choice. Driver and branch duties,
+including planning, dispatch, parent verification, integration, and final audit,
+remain judgment responsibilities outside this leaf field. Tier never weakens a
+leaf's gates, parent re-verification, or integration standard.
+
+`Planned wave` is the earliest intended launch group under the current contract.
+Use a positive integer, put every dependency in an earlier planned wave, and let
+the wave policy cap concurrency. It is a plan, not a barrier: rolling dispatch
+may start a later planned wave as soon as that row's dependencies are verified,
+without waiting for unrelated work. Actual starts belong in `dispatch.json` and
+`status.log`; do not add a second schedule to this file.
+
+Change `Needs`, `Owns`, `Tier`, or `Planned wave` only through a recorded plan
+amendment before that row launches; do not erase a dependency when it becomes
+satisfied. Update `State` in this table as work progresses. After parent
+re-verification and manual review, mark a leaf `VERIFIED`, release that exact
+leaf lease, and record the release. Do not promote a dependent until that exact
+release is recorded. For an abandoned leaf, record the handoff and confirm its
+worker has settled before releasing only that leaf; never call it
+parent-verified. Release the whole scope only after every leaf is settled and
+final scope verification has run. If final verification reports a handoff,
+record it before release and never describe the scope as complete.
+
+## Status log
+
+Append events to `.unlazy/<scope>/status.log`; do not copy the event history into this file:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 dispatched"
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 verified"
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 lease released"
+```
+
+Record contract amendments, plan changes, dispatch, parent verification, abandonment, branch integration, and lease release. Apply logged plan amendments and live State updates only in the dispatch table; keep the log append-only. Before root completion, reread the current request and review every current inventory row against its owner and observing gate or manual review.

package/plugins/maestro-skills/vendor/unlazy/templates/gates-leaf.md

@@ -0,0 +1,51 @@
+# Gates: <leaf or task name>
+
+OWNS: <repository-relative globs this leaf may write, for example src/api/**, tests/api/**>
+
+Scope: <one sentence describing the complete deliverable>
+
+- [ ] G1: <observable outcome measured directly from the artifact>
+  CHECK: node scripts/verify-outcome.mjs
+  EXPECT: outcome verification passed
+  EVIDENCE: pending
+
+- [ ] G2: <integration outcome in a subproject>
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  CWD: packages/example
+  EVIDENCE: pending
+
+- [ ] G3: <manual outcome that no command can decide>
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+Strict format:
+- Use a unique explicit id for every gate.
+- Indent CHECK, EXPECT, CWD, and EVIDENCE.
+- Give a runnable gate both CHECK and EXPECT; give a manual gate neither.
+- Success requires process exit 0 and EXPECT.
+- Make EXPECT a success-only marker produced after every assertion passes.
+- For an absence or negative assertion, test the same checker against a known
+  positive fixture and record that control in the gate's manual review.
+- Measure supplied figures from source. Do not copy a supplied number into
+  EXPECT as its own proof.
+- Use repository-owned Node scripts for portable examples. Declare any
+  non-default shell or external tool requirement explicitly.
+- Scoped and legacy discovery anchor checks at the repository root. When this
+  ledger is named explicitly from `.unlazy/`, pass an explicit repository
+  `--root` and `--cwd` so repository-relative commands keep the same base.
+- Record exact manual evidence and review consequential manual gates by risk.
+- OWNS paths must be repository-relative, complete, and disjoint from every
+  concurrently dispatched leaf. Claims coordinate writers; they do not sandbox.
+
+If a gate becomes genuinely impossible, keep the gate and add:
+
+```text
+ABANDON: G<n> <non-empty reason and handoff>
+```
+
+Surface every abandonment as a non-successful handoff in the final report; an
+abandoned leaf is not complete. See references/gates.md.
+-->

package/plugins/maestro-skills/vendor/unlazy/templates/gates-node.md

@@ -0,0 +1,51 @@
+# Gates: <branch name> integration
+
+Scope: integrate children <explicit child ids> into one verified result
+
+- [ ] N1: every named direct child is reverified from its exact ledger
+  CHECK: node <skill-dir>/scripts/gate-check.mjs --root . --cwd . --reverify --jobs 1 .unlazy/<scope>/gates/leaf-<a>.md .unlazy/<scope>/gates/node-<b>.md
+  EXPECT: ALL MET
+  EVIDENCE: pending
+
+- [ ] N2: child interfaces match the contract in PLAN.md
+  CHECK: node scripts/verify-interfaces.mjs
+  EXPECT: interface verification passed
+  EVIDENCE: pending
+
+- [ ] N3: cross-child behavior works end to end
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  EVIDENCE: pending
+
+- [ ] N4: affected sibling behavior has not regressed
+  CHECK: node scripts/verify-regressions.mjs
+  EXPECT: regression verification passed
+  EVIDENCE: pending
+
+- [ ] N5: every direct leaf child's ownership lease was released after parent verification
+  EVIDENCE: pending
+
+- [ ] N6: consequential manual outcomes from the children were reviewed at branch level
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+N1 must name every direct child ledger explicitly, whether that child is a leaf
+or another branch, and use --reverify, not --status. Status validates the stored
+definition binding without executing or inspecting current artifacts. Keep --jobs 1 unless the child checks are independent and
+deterministic parallel execution is intentional.
+If a child reports an abandonment, N1 exits 1 with `HANDOFF REQUIRED`. Mark the
+branch ABANDONED and surface the handoff; never rewrite that result as completion.
+
+Branch paths use node-<id>.md. Leaf paths use leaf-<id>.md. Branch completion
+requires integration evidence; a set of locally complete leaves is not enough.
+
+For N5, run this once for each direct leaf child after verification and record
+the outputs as manual evidence. Branch children do not own leaf leases:
+
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --leaf leaf-<id> --release
+
+Drop N5 only when no child claimed ownership. See references/orchestration.md
+and references/parallel.md.
+-->

package/scaffold/CLAUDE.md

@@ -351,6 +351,30 @@ This agent is powered by the `@cohortapp/agent-sdk` framework. Update framework:
 - All configs must use environment variables for secrets
 - All actions must be auditable via logs/
 
+### Writing code that survives unattended operation
+
+You run unattended. Nobody is watching when something goes wrong, and your
+daemon, pollers and cadence consumers share one state directory. Code you cannot
+reason about in isolation is code whose failure surfaces days later, in a log.
+So:
+
+- **Decisions are pure functions; I/O happens around them.** Work out *what*
+  should happen from the arguments you were given, then read and write at the
+  edges. A rule you can call without a filesystem is a rule you can test.
+- **`now` is an argument** wherever it changes the answer:
+  `fn(args, now = new Date())`. A schedule that reads the wall clock internally
+  cannot be checked until the moment it fires.
+- **Expected failure is a returned value,** `{ok:false, error}` — not a throw.
+  Throw only when something is genuinely broken.
+- **Every `catch {}` gets a comment** saying why continuing is correct. A silent
+  swallow is a bug you will meet later without a clue where it came from.
+- **Durable JSON is written atomically** — via maestro's `lib/fs-atomic.mjs`
+  (`writeJsonAtomic`) where available. A bare write can leave a half-written
+  file for a concurrent reader to parse.
+- **Prefer adding a file to a registry over editing a dispatcher.**
+- Full doctrine, if maestro is checked out locally:
+  `~/maestro/docs/engineering/functional-architecture.md`.
+
 ## Three Operating Modes
 
 ### Mode 1: Reactive — Respond to Events

package/scripts/ci/check-durable-write-seam.mjs

@@ -0,0 +1,147 @@
+/**
+ * check-durable-write-seam.mjs — the durable-write effect boundary, enforced.
+ *
+ * ── WHAT THIS DEFENDS ────────────────────────────────────────────────────────
+ * `lib/fs-atomic.mjs` is the ONE home for the write-temp → fsync → rename
+ * primitive. Its own docstring names the hazard: a bare `writeFileSync` can
+ * leave a zero-length or half-written file if the process dies mid-write, and a
+ * reader then parses corruption. Because maestro runs daemons, pollers and
+ * cadence consumers concurrently on the same state directory, a torn write is
+ * not a theoretical failure here — it is the observable one.
+ *
+ * ── WHAT THIS RULE CAN SEE ───────────────────────────────────────────────────
+ * A `writeFileSync(` call, in a non-test file under `lib/`, whose argument list
+ * contains `JSON.stringify` — i.e. a write of DURABLE STRUCTURED STATE. That is
+ * the shape worth defending: JSON is what gets read back and parsed, so JSON is
+ * what a torn write corrupts.
+ *
+ * ── WHAT IT DELIBERATELY DOES NOT SEE, and why each is correct ───────────────
+ *   · `writeFileSync(tmp, …)` — a write to a temp sibling that a `renameSync`
+ *     then publishes. That IS the atomic pattern, hand-rolled. It is safe. Some
+ *     30-odd files in `lib/` do exactly this; failing them would make this guard
+ *     noise, and a guard that cries wolf gets suppressed rather than obeyed.
+ *   · `deps.writeFileSync || writeFileSync` — the explicit-dependency form
+ *     (`capability/probe.mjs`, `mandate/cache.mjs`, `plan/emit.mjs`,
+ *     `capability/inventory.mjs`). Injecting the effect is BETTER than routing
+ *     it through a shared helper, not worse. Never flag it.
+ *   · Non-JSON writes — audio buffers, YAML config, `.md` briefs, `.env` stubs,
+ *     marker files like `.emergency-stop`. Torn-write risk is real but the blast
+ *     radius is a re-run, not a parse error in a consumer.
+ *
+ * So this is the cheap first net over one specific, high-value shape. It is not
+ * a proof that `lib/` has no unsafe write.
+ *
+ * ── WHY A REGISTER AND NOT A ZERO ────────────────────────────────────────────
+ * One legitimate spelling survives: acquiring a lock via `O_EXCL`
+ * (`{ flag: "wx" }`). A lock MUST be created exclusively and in place — publish
+ * it by rename and two processes can both believe they hold it, which is the
+ * exact bug the lock exists to prevent. So the check asserts SET EQUALITY
+ * against an explicit register with a reason per entry: a NEW site fails, and a
+ * site that goes away ALSO fails (its register entry is now stale). The register
+ * cannot become a place stale names hide. This is the idiom
+ * `eslint.config.mjs`/`authz-drift.test.ts` use in the Cohort repo.
+ *
+ * Set equality also makes this guard self-canarying: the register is non-empty,
+ * so a regex broken by a refactor yields zero matches and fails LOUDLY as three
+ * stale entries, rather than passing vacuously.
+ *
+ * Pure, dependency-light: Node builtins only. ESM.
+ *
+ * Usage: `node scripts/ci/check-durable-write-seam.mjs`  (exit 0 ok / 1 found)
+ * @module scripts/ci/check-durable-write-seam
+ */
+
+"use strict";
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/**
+ * The sanctioned direct writers of durable JSON, and why each one must be.
+ * `site` is `<repo-relative path>:<line>`; a reason is mandatory.
+ * @type {Record<string, string>}
+ */
+export const SANCTIONED_DIRECT_WRITES = {
+  "lib/cadence-bus.mjs:315":
+    "acquireScheduleLock: O_EXCL create. A lock published by rename is not a lock — two processes could both succeed.",
+  "lib/cadence-bus.mjs:323":
+    "acquireScheduleLock: reclaim of a lock already proven stale by mtime; must land in place under the same name.",
+  "lib/cadence-bus.mjs:328":
+    "acquireScheduleLock: second O_EXCL attempt after the stale holder vanished.",
+};
+
+/** Argument spellings that are already safe and must never be flagged. */
+const TEMP_TARGET_RE = /writeFileSync\(\s*(tmp|temp|tmpPath|tmpFile|fd)\b/;
+const INJECTED_RE = /deps\.writeFileSync/;
+
+/** @param {string} dir @param {string[]} [out] @returns {string[]} */
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules") continue;
+    const p = path.join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (/\.(mjs|js)$/.test(entry) && !/\.test\.(mjs|js)$/.test(entry)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every direct durable-JSON write under `lib/`, as `path:line` → source line.
+ * @param {object} [opts] @param {string} [opts.cwd]
+ * @returns {Array<{ site: string, line: string }>}
+ */
+export function findDirectDurableWrites(opts = {}) {
+  const cwd = opts.cwd || REPO_ROOT;
+  const libDir = path.join(cwd, "lib");
+  const hits = [];
+  for (const file of walk(libDir)) {
+    const rel = path.relative(cwd, file);
+    const lines = readFileSync(file, "utf8").split("\n");
+    lines.forEach((line, i) => {
+      if (!line.includes("writeFileSync(")) return;
+      if (!line.includes("JSON.stringify")) return;
+      if (TEMP_TARGET_RE.test(line)) return;
+      if (INJECTED_RE.test(line)) return;
+      hits.push({ site: `${rel}:${i + 1}`, line: line.trim() });
+    });
+  }
+  return hits;
+}
+
+/** @param {string} [cwd=REPO_ROOT] @returns {Promise<number>} */
+export async function run(cwd = REPO_ROOT) {
+  let hits;
+  try {
+    hits = findDirectDurableWrites({ cwd });
+  } catch (err) {
+    console.error(`check-durable-write-seam: ERROR — ${err && err.message ? err.message : err}`);
+    return 2;
+  }
+  const found = new Set(hits.map((h) => h.site));
+  const registered = new Set(Object.keys(SANCTIONED_DIRECT_WRITES));
+
+  const unregistered = hits.filter((h) => !registered.has(h.site));
+  const stale = [...registered].filter((s) => !found.has(s));
+
+  if (unregistered.length === 0 && stale.length === 0) {
+    console.log(`check-durable-write-seam: OK (${registered.size} sanctioned direct writes, all accounted for)`);
+    return 0;
+  }
+  console.error("check-durable-write-seam: FAIL — the durable-write seam has drifted:");
+  for (const h of unregistered) {
+    console.error(`  NEW  ${h.site}`);
+    console.error(`       ${h.line}`);
+    console.error("       Use writeJsonAtomic() from lib/fs-atomic.mjs, or add a reasoned entry to SANCTIONED_DIRECT_WRITES.");
+  }
+  for (const s of stale) {
+    console.error(`  STALE ${s} no longer matches — delete its SANCTIONED_DIRECT_WRITES entry (reason: ${SANCTIONED_DIRECT_WRITES[s]})`);
+  }
+  return 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().then((c) => process.exit(c)).catch((e) => { console.error("check-durable-write-seam: ERROR", e && e.message ? e.message : e); process.exit(2); });
+}

package/scripts/ci/check-durable-write-seam.test.mjs

@@ -0,0 +1,90 @@
+/**
+ * Tests for check-durable-write-seam.mjs — the durable-write effect boundary.
+ *
+ * Two things are worth testing and they are not the same thing:
+ *   1. The MATCHER's discrimination — that it fires on a direct durable-JSON
+ *      write and stays silent on the three shapes that are already safe
+ *      (temp-then-rename, injected `deps.writeFileSync`, non-JSON payloads).
+ *      A guard that flags safe code gets suppressed, so this is the property
+ *      that decides whether the guard survives contact with contributors.
+ *   2. The REGISTER's honesty against the real tree — that every sanctioned
+ *      site still exists at the line it claims. This is what stops the register
+ *      becoming a place stale names hide.
+ *
+ * @module scripts/ci/check-durable-write-seam.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  findDirectDurableWrites,
+  SANCTIONED_DIRECT_WRITES,
+} from "./check-durable-write-seam.mjs";
+
+const REPO_ROOT = path.resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..");
+
+/** The matcher, lifted verbatim from the guard so a line can be tested alone. */
+function flags(line) {
+  if (!line.includes("writeFileSync(")) return false;
+  if (!line.includes("JSON.stringify")) return false;
+  if (/writeFileSync\(\s*(tmp|temp|tmpPath|tmpFile|fd)\b/.test(line)) return false;
+  if (/deps\.writeFileSync/.test(line)) return false;
+  return true;
+}
+
+describe("check-durable-write-seam: what the matcher sees", () => {
+  it("flags a direct write of durable JSON to a final path", () => {
+    assert.equal(flags('writeFileSync(join(dir, "self.json"), JSON.stringify(entry, null, 2));'), true);
+  });
+
+  it("does NOT flag temp-then-rename — that IS the atomic pattern, hand-rolled", () => {
+    assert.equal(flags('writeFileSync(tmp, JSON.stringify(state, null, 2) + "\\n");'), false);
+    assert.equal(flags("writeFileSync(tmpPath, JSON.stringify(o));"), false);
+  });
+
+  it("does NOT flag the injected-dependency form — that is better than a shared helper, not worse", () => {
+    assert.equal(flags("const wr = deps.writeFileSync || writeFileSync; wr(p, JSON.stringify(o));"), false);
+  });
+
+  it("does NOT flag non-JSON payloads — audio, YAML, markdown, marker files", () => {
+    assert.equal(flags("writeFileSync(join(d, f), audio);"), false);
+    assert.equal(flags("writeFileSync(p, yaml.dump(doc));"), false);
+  });
+});
+
+describe("check-durable-write-seam: the register is honest about the real tree", () => {
+  const hits = findDirectDurableWrites();
+  const found = new Set(hits.map((h) => h.site));
+
+  it("finds at least one site — a matcher that matches nothing passes vacuously", () => {
+    assert.ok(hits.length > 0, "matcher found nothing; it is probably broken");
+  });
+
+  it("every sanctioned site still exists at the line it claims", () => {
+    for (const site of Object.keys(SANCTIONED_DIRECT_WRITES)) {
+      assert.ok(found.has(site), `stale register entry: ${site}`);
+    }
+  });
+
+  it("no unregistered direct durable write exists under lib/", () => {
+    const unregistered = [...found].filter((s) => !(s in SANCTIONED_DIRECT_WRITES)).sort();
+    assert.deepEqual(unregistered, []);
+  });
+
+  it("every sanctioned entry carries a non-empty reason", () => {
+    for (const [site, reason] of Object.entries(SANCTIONED_DIRECT_WRITES)) {
+      assert.ok(reason && reason.length > 20, `register entry ${site} needs a real reason`);
+    }
+  });
+
+  it("the sanctioned sites are all O_EXCL lock acquisition — the one shape rename would break", () => {
+    for (const site of Object.keys(SANCTIONED_DIRECT_WRITES)) {
+      const [rel, lineNo] = site.split(":");
+      const line = readFileSync(path.join(REPO_ROOT, rel), "utf8").split("\n")[Number(lineNo) - 1];
+      assert.match(line, /scheduleLock/, `${site} is not a lock write; it should not be exempt`);
+    }
+  });
+});