agent-coord-mcp 0.26.10 → 0.26.12

package/src/server.ts

@@ -9,6 +9,7 @@ import { z, type ZodRawShape } from "zod";
 import { coordAwaySchema, coordAwayTool, readAway, awayRefusal, secondCoordinatorRefusal } from "./tools/away.js";
 import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool } from "./tools/rotate.js";
 import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
+import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
 import {
   ensureDirs,
   getTokenMap,
@@ -287,7 +288,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "join",
-    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for.",
+    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
     joinSchema,
     // join explicitly sets the session binding when unset, so each agent can
     // declare its identity via join rather than relying on env vars.
@@ -310,7 +311,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "register",
-    "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control.",
+    "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control. `proseOnly:true` claims the per-agent exemption from the typed-record rule, for a model that cannot reliably pick a record.type; it is visible and counted in list_agents, and it is granted to the SENDER but paid by every READER (an untyped message cannot be slimmed). Omit it to leave any existing exemption untouched; pass false to revoke.",
     registerSchema,
     gate("agentId", registerTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -352,14 +353,14 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "list_agents",
-    "List all known agents and whether they appear online (heartbeat <5min).",
+    "List all known agents and whether they appear online (heartbeat <5min). Also reports the prose-only exemptions from the typed-record rule — who holds one, since when, and the count over the total, so a rising exempt share is visible rather than inferred.",
     listAgentsSchema,
     gate(null, listAgentsTool as () => Promise<unknown>),
   );
 
   addTool(
     "send_message",
-    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured.",
+    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured. EVERY AGENT→AGENT MESSAGE MUST CARRY 'record' with a typed 'type' (decision · verdict · done · blocker · risk · fyi · action · go · scope): a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle, while an untyped one arrives in full in every reader's context. 'fyi' is the honest catch-all — use it rather than forcing a false 'decision'/'risk'. Untyped sends WARN today and are REFUSED from 2026-09-15. Messages TO a human are exempt (David-facing traffic stays prose), as is a sender that declared proseOnly:true at join.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -629,11 +630,18 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "subscribe",
-    "Register for a record event: a task completing, a phase completing, or a queue item closing. Events are DERIVED from the record \u2014 emitted by `land` after the DONE entry is written, and refused if the ref is not in the record \u2014 so the stream can never claim something the authoritative markdown does not. Re-subscribing returns the existing registration rather than a duplicate.",
+    "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate.",
     subscribeSchema,
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "scan_record_events",
+    "Turn a repo's COMMITTED record changes into events: new `docs/DONE.md` entries, queue items that left `docs/QUEUE.md`, and newly-ticked phase checkboxes, between the stored watermark and HEAD. The commit is the boundary \u2014 an uncommitted edit is not yet a record. A HAND-EDIT fires exactly like `land` does, which is the point: fleets merge with `gh` and edit DONE.md directly. Reports by default; `write:true` delivers and advances the watermark. Re-scanning a delivered range is safe (the idempotency key comes from the event, so it reports duplicate-suppressed), and a watermark that no longer resolves REFUSES rather than silently narrowing its window.",
+    scanRecordEventsSchema,
+    gate(null, scanRecordEventsTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   addTool(
     "unsubscribe",
     "Remove one of YOUR subscriptions. Refuses another agent's: silently dropping someone else's notification is how a miss is manufactured.",

package/src/tools/events.ts

@@ -13,10 +13,16 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { ROOT } from "../store.js";
+import { EVENT_KINDS, EVENT_KIND_IDS, type RecordEvent, type SubKind } from "./record-events.js";
 
 const subsFile = () => path.join(ROOT, "subscriptions.json");
 
-export type SubKind = "task" | "phase" | "item" | "pr";
+// Re-exported so every existing importer keeps its import path. The vocabulary
+// itself is defined beside the emitters (record-events.ts) — Task 9.2: a kind
+// that can be subscribed to but never emitted is unsatisfiable BY CONSTRUCTION
+// only if the enum cannot be widened without an emitter.
+export { EVENT_KINDS, EVENT_KIND_IDS };
+export type { RecordEvent, SubKind };
 export type Subscription = {
   id: string;
   agentId: string;
@@ -77,8 +83,6 @@ export function subscriptionHealth(s: Subscription): { level: "ok" | "error"; de
 export const eventKey = (kind: SubKind, target: string, ref: string): string =>
   createHash("sha256").update(`${kind}:${target}:${ref}`).digest("hex").slice(0, 16);
 
-export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
-
 /**
  * 6.2 — EVENTS ARE DERIVED FROM THE RECORD, NEVER PARALLEL TO IT.
  *
@@ -139,7 +143,7 @@ export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): {
 
 export const subscribeSchema = {
   agentId: z.string().min(1),
-  kind: z.enum(["task", "phase", "item", "pr"]),
+  kind: z.enum(EVENT_KIND_IDS),
   target: z.string().min(1),
 };
 

package/src/tools/index.ts

@@ -9,3 +9,5 @@ export * from "./work.js";
 export * from "./records.js";
 export * from "./worktrees.js";
 export * from "./stall.js";
+export * from "./events.js";
+export * from "./record-events.js";

package/src/tools/messaging.ts

@@ -1,5 +1,11 @@
 import { adjustCursors } from "./admin.js";
-import { RECORD_AUTHORITY, resolveRole, roleMatches } from "../roles.js";
+import { RECORD_AUTHORITY, isHuman, recordAuthorityFor, resolveRole, roleMatches } from "../roles.js";
+import {
+  TYPED_RECORD_CUTOVER_ISO,
+  suggestRecordType,
+  typedRecordGuidance,
+  typedRecordMode,
+} from "../typed-records.js";
 import { ARCHIVE_STATUS_FILE, ARCHIVE_INBOX_DIR, ARCHIVE_ROOMS_DIR, archiveJsonl, archiveInboxFile, archiveRoomFile } from "../store.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
@@ -159,6 +165,67 @@ export async function checkRecordAuthority(
   };
 }
 
+// ---------- typed records obligatory (Phase 5.1 Task 12) ----------
+
+// An untyped agent→agent message must not be able to EXIST. Enforced HERE, at
+// the send, and not at the render: a rule applied where the message is read
+// leaves the untyped message on disk, and the next reader re-derives the type
+// from prose. See src/typed-records.ts for the staging, the suggestion rules,
+// and why `fyi` stays an honest catch-all.
+//
+// Returns `undefined` when the send is fine, a WARNING string while the rule is
+// staged, or a REFUSAL after the cutover.
+//
+// TWO EXEMPTIONS, AND THEY ARE DIFFERENT IN KIND:
+//   - the RECIPIENT is a human. Canon: "David-facing messages may use normal
+//     prose". Scoped to agent→agent traffic, so the one channel whose reader is
+//     a person is untouched. Nothing is declared for this — it is a property of
+//     who is being written to.
+//   - the SENDER holds a prose-only exemption, declared per agent at join and
+//     visible in list_agents. That one is a statement about a model's ability
+//     to pick a type, and it is paid for by every reader.
+async function typedRecordCheck(args: {
+  from: string;
+  to?: string;
+  text: string;
+  record?: MessageRecord;
+}): Promise<{ ok: true; warning?: string } | { ok: false; error: string }> {
+  if (args.record?.type) return { ok: true };
+
+  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
+
+  // David-facing prose stays prose. An UNREGISTERED recipient is treated as an
+  // agent, not as a human: the safe reading of "I cannot tell" is the rule, and
+  // a human on this bus has a registry entry (that is how the pane is found).
+  if (args.to && isHuman(reg[args.to])) return { ok: true };
+
+  const sender = reg[args.from];
+  if (sender?.proseOnly) return { ok: true };
+
+  const suggestion = suggestRecordType(args.text, recordAuthorityFor(sender).mayNotEmit);
+  const guidance = typedRecordGuidance(suggestion);
+
+  if (typedRecordMode() === "warn") {
+    return {
+      ok: true,
+      warning:
+        `UNTYPED — stored, but this send is REFUSED from ${TYPED_RECORD_CUTOVER_ISO}. ` +
+        `${guidance} Until then an untyped multi-line message arrives in full in every reader's context ` +
+        `instead of one line plus a retrieve_message handle. ` +
+        `A model that cannot pick a type declares proseOnly:true at join (per-agent, visible in list_agents).`,
+    };
+  }
+  return {
+    ok: false,
+    error:
+      `agent→agent messages must carry a typed record (since ${TYPED_RECORD_CUTOVER_ISO}) — nothing was written. ` +
+      `${guidance} ` +
+      `Types: decision · verdict · done · blocker · risk · fyi · action · go · scope; 'fyi' is the honest ` +
+      `catch-all — do not force a false 'decision'/'risk' to get past this. ` +
+      `Messages TO a human are exempt, and an agent that cannot pick a type declares proseOnly:true at join.`,
+  };
+}
+
 export const sendMessageSchema = {
   from: z.string().min(1),
   to: z.string().optional(),
@@ -245,6 +312,12 @@ export async function sendMessageTool(args: {
     };
   }
 
+  // After `text` is resolved (a record can fill it) and before anything is
+  // written, so a refusal leaves nothing on disk.
+  const typed = await typedRecordCheck({ from: args.from, to: args.to, text, record: args.record });
+  if (!typed.ok) return { ok: false as const, error: typed.error };
+  const typedWarning = typed.warning;
+
   let replyWarning: string | undefined;
   if (args.inReplyTo !== undefined) {
     if (!MESSAGE_ID_RE.test(args.inReplyTo)) {
@@ -312,7 +385,7 @@ export async function sendMessageTool(args: {
     const recipientWarning = reg[args.to]
       ? undefined
       : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
-    const warning = [recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
+    const warning = [typedWarning, recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
     return { ok: true, id: msg.id, target, room: undefined, warning };
   }
 
@@ -331,7 +404,7 @@ export async function sendMessageTool(args: {
   const target = roomFile(chan);
   await appendJsonl(target, msg);
   await maybeCompactRoom(chan);
-  const roomWarning = [replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
+  const roomWarning = [typedWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
   return { ok: true, id: msg.id, target, room: chan, ...(roomWarning ? { warning: roomWarning } : {}) };
 }
 

package/src/tools/record-events.ts

@@ -0,0 +1,386 @@
+/*
+ * Phase 5.1 Task 9 — the four subscribable kinds all emit, and the TRIGGER is
+ * the record's COMMITTED CHANGE rather than the `land` verb (David's ruling,
+ * option (b), 2026-08-30).
+ *
+ * WHY NOT (a), "emit from the verbs": it bets on every fleet adopting the
+ * workflow layer, and the only evidence available says they do not — a consumer fleet called
+ * `claim`/`land`/`merge`/`next_unblocked`/`rotate`/`set_halt` ZERO times in a day
+ * of heavy use. A `pr` subscription tested against a real PR came back
+ * `health: error — never evaluated`, and the fleet unsubscribed. Kinds that can
+ * be subscribed to and can never fire are a permanent, honestly-reported error.
+ *
+ * WHAT (b) CHANGES, AND WHAT IT DOES NOT: the record stays the source — only the
+ * trigger moves from the verb to the change. That still satisfies 6.2 ("events
+ * derived from the record, never parallel to it"), because the derivation still
+ * reads the record; it just no longer requires that a particular verb performed
+ * the write. THE POINT IS THAT A HAND-EDIT BECOMES A FIRST-CLASS CAUSE rather
+ * than an invisible one, which is what fleets actually do: they merge with `gh`
+ * and edit `docs/DONE.md` by hand. `land` keeps emitting, as ONE WRITER AMONG
+ * SEVERAL rather than as the gate — the idempotency key makes the overlap safe,
+ * since both paths derive the same key from the same event.
+ *
+ * THE COMMIT IS THE BOUNDARY, not the working tree. An uncommitted edit is not
+ * yet a record: it can be reverted, rebased away, or never pushed, and a
+ * notification for work that then vanishes is worse than a late one.
+ */
+import { execFileSync } from "node:child_process";
+import { newlyTickedInDiff, parseWorkDoc, queueItemsOf, doneEntriesOf } from "@davidbalzan/groundwork-seam";
+/**
+ * The kind vocabulary lives HERE, beside the emitters, and `events.ts` imports
+ * it. That direction is deliberate: it is what makes the enum impossible to
+ * widen without adding an emitter in the same file.
+ */
+export type SubKind = keyof typeof EVENT_KINDS;
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
+
+/*
+ * THE KIND REGISTRY IS THE SINGLE SOURCE, AND THAT IS TASK 9.2.
+ *
+ * `SubKind` used to be a hand-written union next to a hand-written zod enum next
+ * to an emitter that covered one of the four. Nothing connected them, so a kind
+ * could be offered for subscription while nothing could ever emit it — and
+ * `list_subscriptions` would report its permanent `never evaluated` forever,
+ * honestly and uselessly.
+ *
+ * Now the union, the wire enum, and the emitter set are all derived from THIS
+ * object. A kind cannot be offered without an emitter because the enum is
+ * generated from the emitters; `test/record-events.test.mjs` closes the other
+ * half by asserting each kind actually fires. Unsatisfiable BY CONSTRUCTION,
+ * rather than by a reviewer noticing.
+ */
+export const EVENT_KINDS = {
+  item: {
+    record: "docs/QUEUE.md + docs/DONE.md",
+    what: "a queue item closed — it left QUEUE.md and a DONE.md entry appeared in the same commit",
+    targetIs: "the queue item id",
+  },
+  pr: {
+    record: "docs/DONE.md",
+    what: "a PR recorded in the completion log",
+    targetIs: "the PR ref, e.g. owner/repo#163",
+  },
+  task: {
+    record: "docs/phases/**/PHASE*_TASKS.md",
+    what: "a phase task checkbox newly ticked",
+    targetIs: "the task key, e.g. 5:12.1",
+  },
+  phase: {
+    record: "docs/phases/**/PHASE*_TASKS.md",
+    what: "the last open checkbox in a phase document ticked",
+    targetIs: "the phase number, e.g. 5",
+  },
+} as const;
+
+export const EVENT_KIND_IDS = Object.keys(EVENT_KINDS) as [SubKind, ...SubKind[]];
+
+/**
+ * One pass over the diff → per-file added and removed lines.
+ *
+ * Per FILE, not per predicate: the phase rule needs to know WHICH document a
+ * tick came from, and a flat "all added lines" view cannot answer that. It
+ * emitted `phase 5 complete` off a tick in the phase 5.1 document on the first
+ * real-data run.
+ */
+export function diffByFile(diff: string): Map<string, { added: string[]; removed: string[] }> {
+  const out = new Map<string, { added: string[]; removed: string[] }>();
+  let cur: { added: string[]; removed: string[] } | null = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("diff --git ")) { cur = null; continue; }
+    if (line.startsWith("+++ b/")) {
+      const p = line.slice(6).trim();
+      if (p === "/dev/null") { cur = null; continue; }
+      cur = out.get(p) ?? { added: [], removed: [] };
+      out.set(p, cur);
+      continue;
+    }
+    if (line.startsWith("--- a/") || line.startsWith("@@")) continue;
+    if (!cur) continue;
+    if (line.startsWith("+")) cur.added.push(line.slice(1));
+    else if (line.startsWith("-")) cur.removed.push(line.slice(1));
+  }
+  return out;
+}
+
+const isDone = (p: string) => /(^|\/)DONE\.md$/.test(p);
+const isQueue = (p: string) => /(^|\/)QUEUE\.md$/.test(p);
+const isPhaseDoc = (p: string) => /PHASE[^/]*TASKS\.md$/i.test(p);
+
+const linesWhere = (byFile: ReturnType<typeof diffByFile>, match: (p: string) => boolean, side: "added" | "removed") =>
+  [...byFile.entries()].filter(([p]) => match(p)).flatMap(([, v]) => v[side]);
+
+/**
+ * A ref that actually identifies a pull request.
+ *
+ * MEASURED ON REAL DATA, and this is why the check exists: the done-entry
+ * parser splits on the LAST ` — `, so an entry whose own text contains an em
+ * dash yields a "ref" of `aide-verified, coordinator-closed`. Emitting that as
+ * a `pr` event would put a target on the bus that names no PR, and a
+ * subscription could never match it — a silent, permanent miss dressed as a
+ * delivery. Parsing correctly is not the same as the parse MEANING what you
+ * assumed.
+ */
+const PR_REF = /^(?:[\w.-]+\/[\w.-]+#\d+|#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)$/;
+
+/** Queue and done text, compared for the pairing below. */
+const norm = (s: string) => String(s).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+
+/**
+ * Events implied by one committed change.
+ *
+ * `after` carries the documents AS THEY NOW STAND — every event is checked
+ * against them by the caller (`eventIsDerived`), so a diff that has since been
+ * reverted cannot produce an event that outlives the record.
+ */
+export function eventsFromCommittedChange(
+  diff: string,
+  after: { done?: string; phases?: Record<string, string> } = {},
+): RecordEvent[] {
+  const events: RecordEvent[] = [];
+  const unattributedItems: string[] = [];
+  const byFile = diffByFile(diff);
+
+  // ── pr: a new DONE.md entry naming a PR ───────────────────────────────────
+  // Parsed, never regexed off the raw line: the glyph contract (` — ` U+2014,
+  // ` · ` U+00B7) is exact, and a hand-written entry using a plain hyphen must
+  // NOT quietly become an event with a mangled ref. It fails to parse, and a
+  // line that does not parse is not a record entry.
+  const addedDone = linesWhere(byFile, isDone, "added");
+  const newEntries = doneEntriesOf(parseWorkDoc(`## Done\n${addedDone.join("\n")}\n`)) as Array<{ ref?: string; text?: string }>;
+
+  for (const entry of newEntries) {
+    const ref = entry.ref?.trim();
+    if (!ref || !PR_REF.test(ref)) continue;
+    events.push({ kind: "pr", target: ref, ref, summary: entry.text?.slice(0, 120) || ref });
+  }
+
+  // ── item: a queue item that closed ────────────────────────────────────────
+  //
+  // ATTRIBUTION IS THE WHOLE PROBLEM, and the markdown does not carry it. A
+  // queue item and the DONE entry that closes it share no id and, on real data,
+  // no wording either: the item states what to do and the entry states what was
+  // done. `land` only knows because its caller passed `queueItemId`.
+  //
+  // So: pair on text when the texts DO correspond, otherwise pair only when the
+  // commit is unambiguous — exactly one item removed and exactly one entry
+  // added. Anything else is reported as unattributed rather than guessed. The
+  // naive version attributed all 15 items removed in one real commit to the
+  // first PR it saw, which is a wrong claim about fourteen of them, and a wrong
+  // claim on this bus is worse than a missing one.
+  const removedQueue = linesWhere(byFile, isQueue, "removed");
+  const removedItems = (queueItemsOf(parseWorkDoc(`## Queue\n${removedQueue.join("\n")}\n`)) as Array<{ id?: string; text?: string }>)
+    .filter((i) => i.id);
+  const prEntries = newEntries.filter((e) => e.ref && PR_REF.test(e.ref.trim()));
+  const unattributed: string[] = [];
+
+  for (const item of removedItems) {
+    const itemText = norm(item.text ?? "");
+    let entry = itemText
+      ? prEntries.find((e) => {
+          const t = norm(e.text ?? "");
+          return t && (t === itemText || t.startsWith(itemText) || itemText.startsWith(t));
+        })
+      : undefined;
+    // The unambiguous-commit case: one out, one in. This is the shape the fleet
+    // actually commits ("close its queue item"), and it is the case the aide's
+    // dead `item` subscriptions need.
+    if (!entry && removedItems.length === 1 && prEntries.length === 1) entry = prEntries[0];
+    if (!entry) {
+      unattributed.push(item.id!);
+      continue;
+    }
+    events.push({ kind: "item", target: item.id!, ref: entry.ref!.trim(), summary: entry.text?.slice(0, 120) ?? item.id! });
+  }
+  if (unattributed.length) unattributedItems.push(...unattributed);
+
+  // ── task: checkbox transitions ────────────────────────────────────────────
+  // `newlyTickedInDiff` requires BOTH a removed open box and an added ticked one
+  // for the same id, so a moved or reformatted line cannot manufacture a
+  // completion — that rule is the seam's and is reused rather than re-derived.
+  const ticked = [...newlyTickedInDiff(diff)];
+  const tickedLines = linesWhere(byFile, isPhaseDoc, "added");
+  for (const key of ticked) {
+    const id = key.split(":")[1] ?? "";
+    // Ref is the ticked LINE, not the bare id: `12.1` appears in prose all over
+    // a phase doc, so a bare id would pass the derivation check against a
+    // document that never ticked anything.
+    const line = tickedLines.find((l) => new RegExp(`^\\s*-\\s*\\[x\\]\\s*\\*{0,2}${id.replace(".", "\\.")}\\b`, "i").test(l));
+    if (!line) continue;
+    events.push({ kind: "task", target: key, ref: line.trim(), summary: line.trim().slice(0, 120) });
+  }
+
+  // ── phase: the last open box in ONE document ──────────────────────────────
+  // Keyed on the FILE, both for "is it complete" and for "did this change close
+  // it". `newlyTickedInDiff` keys ticks by the integer in the path, so
+  // `phase5.1` and `phase5` collapse to the same `5:` — the first real-data run
+  // announced PHASE 5 COMPLETE on the strength of a tick in the 5.1 document.
+  // A false completion is worse than a missing one: it closes a phase nobody
+  // finished.
+  for (const [rel, text] of Object.entries(after.phases ?? {})) {
+    if (!isPhaseDoc(rel)) continue;
+    const boxes = [...String(text).matchAll(/^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+[a-z]?)\b/gim)];
+    if (!boxes.length || boxes.some((m) => m[1] !== "x")) continue;
+    // This commit must have ticked a box IN THIS FILE.
+    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => /^\s*-\s*\[x\]\s*\*{0,2}\d+\.\d+/.test(l));
+    if (!closedHere) continue;
+    const phase = /phase(\d+(?:\.\d+)?)/i.exec(rel)?.[1];
+    if (!phase) continue;
+    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]![0].trim(), summary: `phase ${phase} — every task box ticked` });
+  }
+
+  lastUnattributedItems = unattributedItems;
+  return events;
+}
+
+/**
+ * Queue item ids removed in the last scanned change that could NOT be tied to a
+ * done entry. Reported by `scan_record_events` rather than dropped: "we saw
+ * items close and could not say which PR closed them" and "nothing closed" are
+ * different facts, and only one of them needs a human.
+ */
+export let lastUnattributedItems: string[] = [];
+
+/** `git` in a repo, returning "" rather than throwing — a scan is read-only. */
+export function git(repo: string, args: string[]): string {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  } catch {
+    return "";
+  }
+}
+
+/* ── the verb ──────────────────────────────────────────────────────────────── */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived } from "./events.js";
+
+/**
+ * The watermark: the last commit whose record change has been turned into
+ * events, per repo.
+ *
+ * It is stored rather than inferred, because "what have I already emitted" is
+ * not derivable from the repo — and the alternative, re-deriving from some
+ * fixed point every time, would re-announce a year of closures on first run.
+ * Losing the file is safe in the direction that matters: the idempotency key is
+ * derived from the EVENT, so a re-scan of already-delivered events reports
+ * `duplicate-suppressed` rather than waking anyone twice.
+ */
+const watermarkFile = () => path.join(ROOT, "record-events.json");
+
+type Watermarks = Record<string, { sha: string; at: number }>;
+
+function readWatermarks(): Watermarks {
+  const f = watermarkFile();
+  if (!existsSync(f)) return {};
+  try {
+    return (JSON.parse(readFileSync(f, "utf8")).repos ?? {}) as Watermarks;
+  } catch {
+    return {};
+  }
+}
+
+function writeWatermark(repo: string, sha: string): void {
+  mkdirSync(ROOT, { recursive: true });
+  const all = readWatermarks();
+  all[repo] = { sha, at: Date.now() };
+  writeFileSync(watermarkFile(), `${JSON.stringify({ repos: all }, null, 2)}\n`);
+}
+
+export const scanRecordEventsSchema = {
+  repo: z.string().min(1),
+  /** Defaults to the stored watermark; first run with none scans HEAD~1..HEAD. */
+  since: z.string().optional(),
+  /** Report only. Default true — same posture as `land` and `next_unblocked`. */
+  write: z.boolean().optional(),
+};
+
+export async function scanRecordEventsTool(args: { repo: string; since?: string; write?: boolean }) {
+  const repo = path.resolve(args.repo);
+  if (!existsSync(path.join(repo, ".git"))) {
+    return { ok: false as const, error: `'${repo}' is not a git repository — the commit is the boundary for a record change, so there is nothing to scan` };
+  }
+
+  const head = git(repo, ["rev-parse", "HEAD"]).trim();
+  if (!head) return { ok: false as const, error: `could not resolve HEAD in ${repo}` };
+
+  const stored = readWatermarks()[repo]?.sha;
+  const since = args.since ?? stored ?? `${head}~1`;
+  // A watermark from a rebased-away commit resolves to nothing. Say so rather
+  // than silently falling back to HEAD~1 and reporting a one-commit scan as if
+  // it covered the gap — that is the shape where a miss looks like a clean run.
+  if (!git(repo, ["cat-file", "-e", `${since}^{commit}`]) && !git(repo, ["rev-parse", "--verify", `${since}^{commit}`]).trim()) {
+    return {
+      ok: false as const,
+      error:
+        `base '${since}' does not resolve in ${repo} — it was probably rebased away. ` +
+        `Nothing was scanned and the watermark was NOT advanced: a scan that silently narrows its window ` +
+        `reports a clean run over the commits it never looked at. Pass an explicit 'since'.`,
+    };
+  }
+
+  const diff = git(repo, ["diff", "--unified=0", `${since}..${head}`, "--", "docs/"]);
+  const doneText = existsSync(path.join(repo, "docs/DONE.md")) ? readFileSync(path.join(repo, "docs/DONE.md"), "utf8") : "";
+  const phases: Record<string, string> = {};
+  for (const rel of git(repo, ["ls-files", "docs/phases/"]).split("\n").filter((p) => /PHASE[^/]*TASKS\.md$/i.test(p))) {
+    const p = path.join(repo, rel);
+    if (existsSync(p)) phases[rel] = readFileSync(p, "utf8");
+  }
+
+  const candidates = eventsFromCommittedChange(diff, { done: doneText, phases });
+  const unattributed = [...lastUnattributedItems];
+
+  // Every event is checked against the record AS IT NOW STANDS (6.2). A change
+  // that has since been reverted produces a candidate the record no longer
+  // supports, and it is refused — the stream can never claim what the
+  // authoritative markdown does not.
+  const emitted: RecordEvent[] = [];
+  const refused: string[] = [];
+  for (const ev of candidates) {
+    const recordText = ev.kind === "task" || ev.kind === "phase" ? Object.values(phases).join("\n") : doneText;
+    const derived = eventIsDerived(recordText, ev);
+    if (derived.ok) emitted.push(ev);
+    else refused.push(derived.error);
+  }
+
+  const deliveries: unknown[] = [];
+  if (args.write) {
+    let subs = readSubs();
+    const now = Date.now();
+    for (const ev of emitted) {
+      const r = evaluate(subs, ev, now);
+      subs = r.subs;
+      deliveries.push(...r.deliveries);
+    }
+    commitEvaluation(subs);
+    writeWatermark(repo, head);
+  }
+
+  return {
+    ok: true as const,
+    repo,
+    scanned: { from: since, to: head },
+    emitted,
+    refused,
+    deliveries,
+    ...(unattributed.length
+      ? {
+          unattributedItems: unattributed,
+          unattributedNote:
+            `${unattributed.length} queue item(s) left docs/QUEUE.md in this range without a done entry they could be tied to. ` +
+            `They emitted NOTHING: the markdown carries no link between an item and the entry that closes it, so attributing them ` +
+            `would be a guess. "Closed by an unknown PR" and "not closed" are different facts and this is the first.`,
+        }
+      : {}),
+    ...(args.write
+      ? { watermark: head }
+      : {
+          note:
+            "REPORT ONLY — nothing was delivered and the watermark was not advanced. Pass write:true to deliver. " +
+            "Re-scanning an already-delivered range is safe: the idempotency key is derived from the event, so it reports duplicate-suppressed.",
+        }),
+    kinds: EVENT_KINDS,
+  };
+}