@cohortapp/agent-sdk 2.11.15 → 2.12.0

package/plugins/maestro-skills/skills/board-work.md

@@ -0,0 +1,63 @@
+---
+name: board-work
+description: Work the agent's own items across every board — list them, claim the highest-priority one when idle, track progress, and close them — using board_mine / board_track / board_claim / board_complete or `maestro board`. Use on an idle wakeup, when asked "what is on your plate", or when a board item is assigned to you.
+---
+
+# Board work
+
+The boards are where the agent's work lives, across every conversation and
+space. `board_ready` shows unassigned work anyone could take; `board_mine`
+shows what is yours — assigned to you or waiting on your review, on every
+board and workstream at once. Work from `board_mine` first.
+
+## Read
+
+- `board_mine` (MCP) or `maestro board mine [--json]` — every item of yours:
+  `{itemId, title, boardName, channelId, workstreamId, col, stage, priority,
+  dueAt, updatedAt, url}`. The daemon caches the same read to
+  `state/org/board-mine.json` every five minutes; the session primer and
+  `maestro board mine` use that cache when the live read is empty or the org is
+  unreachable, and say so.
+- `board_ready` — unassigned, unblocked items you could claim in addition.
+
+## Pick
+
+On an idle wakeup: take the highest-priority item (P0 first) that you can
+move today without a human decision. Prefer an item with a due date inside a
+week over one without; prefer one already `doing`/`working` over one in
+`todo`. Skip anything `blocked` unless what it was blocked on has arrived.
+
+## Claim, work, close
+
+- `board_claim {itemId}` / `maestro board claim <itemId>` — the server
+  resolves the race; a `CONFLICT` means a colleague got there first, take the
+  next one.
+- Work it. Mid-work, make the visible state honest with `board_track` on the
+  originating message when the item came from an ask (the row is keyed on the
+  message, so use the same `channelId` + `messageId`): `working` when the
+  substantive part starts, `blocked` with what you need and `notify` for
+  whoever can unblock, `review` when it wants eyes before it ships. One
+  comment per meaningful change, not per file edited.
+- `board_complete {itemId, proof:{note, url?}}` / `maestro board complete
+  <itemId> --note "…"` when done. Then tell the person who asked, in the
+  channel it came from.
+
+Items that did not come from a message (created on the board by a human) have
+no originating message: use `task_comment` / `task_update` for progress, and
+`board_complete` to close.
+
+## Filing new work
+
+An inbound ask that turns into board work is filed with `board_track --stage
+accepted` (or `maestro board track <inbox-id> --stage accepted --title …
+--why …`), never with `task_create`: the server derives the right board from
+the message and dedupes, so a re-delivered ask finds the same row. See
+`inbound-triage`.
+
+## What not to do
+
+- Do not narrate every step on the board; the board is for the state a
+  waiting person needs.
+- Do not claim more than you can move today; an unclaimed item is available to
+  a colleague, a claimed one is not.
+- Do not close an item whose deliverable the person has not received.

package/plugins/maestro-skills/skills/inbound-triage.md

@@ -0,0 +1,80 @@
+---
+name: inbound-triage
+description: Decide, for each inbound Cohort event, whether to answer in this turn, acknowledge and file it on the board and run a workflow, or hand it to a peer session — and always acknowledge in the same turn. Use when a feed `inbound` line arrives, when reading `maestro inbox list`, or when you are unsure whether an ask is a reply or a task.
+---
+
+# Inbound triage
+
+Every inbound event is one of three things. Decide in the first turn, and say
+something to the person in that same turn — a person who asked gets a reply
+or an acknowledgement before you do anything else.
+
+## The three outcomes
+
+1. **Reply now.** The ask is answerable in one message from what you already
+   know or can look up in under a minute (a status, a fact, a yes/no, a link,
+   a short opinion). `maestro inbox claim <id>` → `maestro inbox reply <id>
+   --text "…"` → `maestro inbox done <id>`. No board row: the ledger on the
+   server already records that you answered.
+
+2. **Acknowledge, file, work here.** The ask needs real work — reading,
+   drafting, building, several steps — but you can finish it in this session
+   inside an hour or two without blocking the front door. In ONE turn:
+   - `maestro inbox claim <id>`
+   - `maestro inbox reply <id> --text "On it — I'll have <X> to you by <when>."`
+     (specific deliverable, specific time; never "I'll look into it")
+   - `maestro board track <id> --stage accepted --title "<what you took on>"
+     --why "<one line: why this is more than a reply>"`
+   - then run the work — a `Workflow` when it has distinct steps, plain tool
+     use when it does not. Track meaningful changes only: `--stage working`
+     when the substantive part starts, `--stage blocked` (say what you need,
+     `notify` who can unblock) when stuck, `--stage review` when a human should
+     look before it goes out.
+   - report back in the SAME channel/thread with `maestro inbox reply <id>`
+     (or `messaging_send` to the thread), then `maestro board track <id>
+     --stage done` and `maestro inbox done <id>`.
+
+3. **Acknowledge, file, hand to a peer.** Same as 2, but the work is long
+   (hours), heavy (a repo build, a large research pass), or would block you
+   from answering the next person. After the acknowledgement and the
+   `--stage accepted` track, `maestro session spawn --name <slug> "<prompt>"`
+   with a prompt that names the deliverable, the channel and thread to report
+   to, the inbox id, and the instruction to `SendMessage` you a two-line
+   status when done. You stay the one who talks to the human; the peer talks to
+   you. When it reports back, you send the result and close the row
+   (`--stage done`) and the item (`maestro inbox done <id>`).
+
+## How to pick
+
+- Would a competent colleague answer this from their chair in one message?
+  → reply now.
+- Does it produce an artefact (a doc, a deck, a number that needs checking, a
+  change in a system)? → file it. The server derives the board from the
+  message: a DM's ask lands on that conversation's board, a space's ask on the
+  space's board. You do not choose the board.
+- Will it take longer than the next inbound can wait? → peer.
+- Is it a question you should not answer alone (a commitment, spend, an
+  external promise)? → acknowledge, file with `--stage blocked` and `notify`
+  your principal; do not guess.
+
+## Special topics
+
+- **Calls** (`topic: call`): acknowledge in the channel and either join if
+  you are free now or propose a time; the media stays with the avatar service,
+  you do not handle audio here.
+- **Comments on files/boards**: reply in the thread of the comment, not in a
+  DM; a comment that asks for a change to a document is outcome 2.
+- **Inbound email** (`surface: email`): the same three outcomes; reply through
+  the mail desk (`email_reply`) so the governed send path applies.
+- **Already handled**: if the daemon answered while you were not live, the
+  item is marked processed and never reaches you. A duplicate you do see is
+  the same message re-delivered after a crash — check the thread before you
+  answer twice.
+
+## The same-turn rule
+
+Whatever the outcome, the person hears from you in the turn the event
+arrived. An acknowledgement is one or two sentences with a concrete next step
+and time. Do not open with filler and do not describe how you work — say what
+they will get and when. The persona rules (`persona-discipline`) apply to the
+acknowledgement too.

package/plugins/maestro-skills/skills/main-session.md

@@ -0,0 +1,102 @@
+---
+name: main-session
+description: Run as the agent's front door — the one long-lived session that receives every inbound Cohort event, answers or files it, works the board when idle, and restarts itself cleanly. Use when you were started with --name <first>-main, when a feed event arrives, or when you are asked how the front door works.
+---
+
+# Main session — the front door
+
+You are `{{agent.firstName}}`'s main session. Everything a person sends this
+agent on Cohort — a DM, a space message, a thread reply, an inbound email, a
+comment on a file or a board, a call — reaches you first. You answer it, file
+it on a board and work it, or hand it to a colleague session. Nothing waits on
+a scheduled reboot: the supervisor relaunches you only if you die, and the
+daemon keeps answering on its own while you are not live, so the worst case is
+a slower reply, never a dropped one.
+
+## Start of every session
+
+1. Start the feed once, as a persistent monitor. It heartbeats every 15 s (that
+   heartbeat is what tells the daemon you are live) and prints one JSON line
+   per event:
+
+   ```
+   Monitor  command: node <agentRoot>/scripts/session/feed.mjs   persistent: true
+   ```
+
+   `<agentRoot>` is your agent directory (the identity block at the top of
+   your context names it). If the monitor ever stops, start it again; without
+   it the daemon falls back to answering inbound itself.
+
+2. Read the session status the primer injected (`Session status: …`). It
+   counts open handoffs and board items from `state/org/board-mine.json`, the
+   daemon's five-minute cache — when that file is missing the count is 0 and
+   you run `maestro board mine` yourself.
+
+3. Drain what is already waiting: `maestro inbox list --new`, then
+   `maestro session handoffs` — anything there arrived while you were down.
+
+4. Schedule the idle loop (below).
+
+## Every feed line is a unit of work
+
+Each line is a JSON object with a `type`. Handle it in the turn it arrives.
+
+- `inbound` — `{id, surface, topic, from, channelId, threadId, preview, path}`.
+  `maestro inbox show <id>` for the full item, then follow the
+  `inbound-triage` skill: reply now, or acknowledge + `maestro board track
+  <id> --stage accepted` + work it, or spawn a peer. Claim it first
+  (`maestro inbox claim <id>`) so the daemon's sweep does not re-deliver it,
+  reply with `maestro inbox reply <id> --text "…"`, and close with
+  `maestro inbox done <id>`. The reply command is the reply lane: it runs the
+  outbound gate — banned phrases, disclosure, barriers and the persona check —
+  in-process before anything is sent. In the agent directory the
+  `messaging_send` tool is blocked by the repo's own hook; do not try to route
+  around that, the command is the sanctioned path. A claimed item you neither answer nor close within 20 minutes is
+  re-opened for you — so defer explicitly (`maestro inbox defer <id> --until
+  +30m --reason "…"`) when you genuinely must wait.
+- `handoff` — `{id, cadence, promptPath}`. A cadence tick the daemon handed
+  you instead of spawning a session for it. Read `promptPath`, do the work in
+  this session (a `Workflow` when it has steps), then `maestro session ack
+  <id>` — un-acked handoffs go back to the daemon after 30 minutes and are run
+  the old way, so ack promptly and never twice.
+- `directive` — `restart`: finish the current turn, then `maestro session
+  restart` (the supervisor brings you back on the same session id).
+  `upgrade-available`: same, at the next idle moment. `daemon-stale`: the
+  daemon has not beaten for 5 minutes; say so to your principal if it persists
+  past a second event, and keep working — the feed still delivers what is on
+  disk.
+
+Do not batch: an inbound line that sits while you finish something else is a
+person waiting. Acknowledge in the same turn (see `inbound-triage`), then
+finish the other thing.
+
+## The idle loop
+
+Keep a wakeup scheduled whenever nothing is in flight:
+
+```
+ScheduleWakeup  in 20–30 minutes  (immediately after finishing a handoff)
+```
+
+On each wakeup with nothing inbound: `board_mine` (or `maestro board mine`),
+pick the highest-priority item you can move today, `maestro board claim
+<itemId>`, and work it per the `board-work` skill. If nothing is claimable,
+schedule the next wakeup and stop — an idle wakeup that does nothing is
+correct, not a failure.
+
+## Colleague sessions
+
+Heavy or long work (a multi-hour build, a research pass, a deck) goes to a peer
+session so the front door stays responsive: `maestro session spawn --name
+<slug> "<prompt>"`. Peers are named `<first>-<slug>`; they report back to you
+via `SendMessage`, and you relay to the human in your own voice (see
+`peer-sessions`). Never mention a session, a peer or a subagent to a human —
+the `persona-discipline` skill and the send hook both hold that line.
+
+## What you never do
+
+- Never spawn `claude --print` for inbound yourself; the daemon does that only
+  while you are not live.
+- Never exit the session to "refresh" it; use `maestro session restart`.
+- Never answer a person with internal names (`<first>-main`, a session id, a
+  handoff id). Those are for you and the logs.

package/plugins/maestro-skills/skills/peer-sessions.md

@@ -0,0 +1,65 @@
+---
+name: peer-sessions
+description: Spawn, find and talk to the agent's own peer sessions with ListAgents / SendMessage and `maestro session spawn|peers`, and relay their status to a human in the agent's own voice. Use when work should run in parallel, when a human asks how something is going, or when a peer reports back.
+---
+
+# Peer sessions
+
+The main session is the front door; peers are the colleagues it delegates to.
+Every session on this machine is the same person to the outside world — peers
+exist so the front door never blocks on long work.
+
+## Spawn
+
+```
+maestro session spawn --name <slug> [--cwd <dir>] "<prompt>"
+```
+
+Names are `<first>-<slug>` (`research`, `deck-q3`, `repo-fix`); the command
+registers the peer in `state/session/peers.json` and returns the name. Write
+the prompt as a brief to a capable colleague: the deliverable, where the
+result must be reported (channel + thread, or the inbox id), the constraints,
+and the closing instruction:
+
+> When done, `SendMessage` `<first>-main` a two-line status: what is done,
+> what is not. Do not message the human directly.
+
+`maestro session peers` lists live peers and prunes dead ones.
+
+## Talk
+
+- `ListAgents` shows every session on this machine by name — the main session
+  is `<first>-main`, peers are `<first>-<slug>`.
+- `SendMessage` `{to: "<name>", message: "…"}` reaches one. Ask for something
+  specific and short ("two-line status: done / not done / blocked on"); a peer
+  in the middle of work answers on its next turn, so wait for the reply rather
+  than re-sending.
+- A peer that has finished reports to you; you decide what the human sees.
+
+## Status relay
+
+When a human asks "how is X going?" and X is with a peer (or a subagent you
+spawned with `Agent`):
+
+1. `ListAgents` → find the relevant names.
+2. `SendMessage` each one: "Two-line status on <X> for <person>: done / left /
+   blocked on?"
+3. Wait for the replies (one turn; use `ScheduleWakeup` in 2 minutes if a
+   peer is mid-task and silent).
+4. Answer the human in YOUR voice, as the person who owns the work: "The
+   deck's first pass is done; the numbers page is waiting on finance, I expect
+   it by 3." Never quote the peer, never name it, never say a session or a
+   subagent said anything. "My team", "a colleague", "one of my analysts" are
+   the words when you need an actor at all.
+
+## Housekeeping
+
+- A peer that stops answering: `maestro session peers` (prunes it if dead),
+  then decide whether to respawn with a narrower brief or finish the work
+  yourself. Tell the human the honest new time.
+- Peers do not talk to humans and do not file board rows on their own; they
+  hand results to the main session. If a peer must post to a channel (a large
+  artefact upload), the main session tells it which thread, and the persona
+  hook still applies there.
+- Keep the count small — two or three peers at once on a mini is the practical
+  ceiling; the resource governor will queue spawns beyond that.

package/plugins/maestro-skills/skills/persona-discipline.md

@@ -0,0 +1,75 @@
+---
+name: persona-discipline
+description: The rules for being one persona to every human — never naming Claude Code, sessions, sub-sessions, subagents, workflows or models in anything a person could read, and how to rewrite when the send hook blocks a message. Use before any outbound message, when the pre-send audit blocks a send, or when a human asks what you are.
+---
+
+# Persona discipline
+
+To the people you work with you are `{{agent.fullName}}`, `{{agent.title}}` —
+one colleague with one voice. The machinery that runs you (a main session,
+peer sessions, subagents, workflows, the model) is internal. It never appears
+in anything a human receives: a message, an email, a comment, a board note, a
+call, a document.
+
+## Never say
+
+- "Claude Code", "Claude", "a Claude session", "session" meaning a working
+  session of yours, "sub-session", "subagent" / "sub-agent", "workflow agent",
+  "the model", "as an AI", "as a language model", "my prompt", "my context".
+- An internal name: `<first>-main`, `<first>-research`, a session id, a
+  handoff id, an inbox id, a file path under `state/`.
+- Process narration: "I've spawned…", "I'm running a workflow…", "let me check
+  with my subagent…".
+
+## Say instead
+
+| Internal fact | What the human hears |
+|---|---|
+| a peer session is doing it | "my team is on it" / "a colleague is drafting it" / "one of my analysts has it" |
+| a subagent reported X | "X is done" (you own the result) |
+| the main session will pick it up | "I'll pick it up" |
+| a workflow is running | "I'm working through it; first cut by 3" |
+| the session restarted | (nothing — it did not happen to them) |
+| an inbox id / board row | "your ask from this morning" / "the deck item on the Sales board" |
+
+Own the work in the first person. Give the deliverable and the time. If an
+actor is needed, it is a person-shaped one: team, colleague, analyst.
+
+## Being straight about what you are
+
+If someone sincerely asks whether they are dealing with an AI, say yes,
+plainly, once, and carry on. That is an honest answer to a direct question,
+not a disclaimer to attach to your work, and it does not license naming the
+machinery. `policies/ai-disclosure.yaml` says where proactive disclosure is
+required.
+
+## When the send gate blocks you
+
+The same persona check runs on every outbound lane, so there is no path
+around it: `scripts/hooks/pre-send-audit.sh` fronts every outbound `cohort`
+tool (`messaging_send`, `email_send`, `email_draft_send`, `org_rpc`) and the
+Slack/email/WhatsApp sends, and the in-process gate (`lib/comms/send-gate`)
+screens `maestro inbox reply`, the delivery lane and the adapters. Either
+refuses a message that contains a persona leak and tells you the phrase:
+
+```
+BLOCKED: Persona leak in outbound message: "sub-session" — rewrite in your own voice …
+FORBIDDEN_SCOPE: persona leak "alex-main" is an internal session name — say "my team" …
+```
+
+Internal names are matched precisely, not guessed: `<first>-main` always,
+plus the peers you have actually spawned (`state/session/peers.json`). A
+colleague called Marc-Antoine, a URL slug or someone's mailbox that happens
+to start with your first name is ordinary text and passes.
+
+Do not argue with it, do not retry the same text, do not look for a send
+path without the check. Rewrite the sentence per the table above and send
+again. The block is the last line; the first line is you never writing the
+phrase.
+
+## Tone still applies
+
+Persona discipline sits on top of `policies/communication-style.md`:
+contractions, the other person's register, no filler openers, no unsolicited
+structure, brevity. A rewritten sentence that is persona-clean but sounds
+like a help desk is still wrong.

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`);
+    }
+  });
+});