agent-coord-mcp 0.26.21 → 0.26.23

package/src/tools/board-ref.ts

@@ -49,6 +49,16 @@ import { execFileSync } from "node:child_process";
 export type BoardRefVerdict =
   | { kind: "measurable"; ref: string }
   | { kind: "empty"; why: string }
+  /**
+   * ⟨q-5d1c8e04⟩ — A DELIBERATE NO-BRANCH. The cell holds WORDS in the ref
+   * position (`docs-direct · no per-agent branch`, `own clone …`): a human
+   * statement that this lane carries no per-agent branch. Out of the stall
+   * clock's population, never "unmeasurable" — five seats wrote this shape
+   * because the grammar gave them no other way to say it.
+   */
+  | { kind: "none"; why: string }
+  /** A ref a human ABBREVIATED for display (`…/kit-worker-lane`) — unreadable by construction, and said so. */
+  | { kind: "elided"; why: string }
   | { kind: "path"; why: string }
   | { kind: "shared"; why: string }
   | { kind: "unscoped"; why: string }
@@ -84,9 +94,51 @@ const isSyntacticallyValidRef = (name: string): boolean => {
   }
 };
 
-/** The `\`ref\`` inside a `Branch · Worktree` cell, or "". */
+/*
+ * ⟨q-5d1c8e04⟩ — THE CELL GRAMMAR, read by POSITION rather than by scanning.
+ *
+ *   \`ref\` · <path>     the ref is the LEADING backticked token; what follows is a note
+ *   —  (or blank)        nothing declared — on a lane row this is "lacks a branch"
+ *   <prose>              a deliberate statement: this row carries no per-agent branch
+ *
+ * `refInCell` used to take the FIRST backticked token ANYWHERE, so the aide's
+ * `**own clone \`groundwork-kit-aide-write\`** (ADR-016, \`a7bd341\`)` yielded a
+ * clone name that was then looked up as `origin/groundwork-kit-aide-write` and
+ * reported "unpushed" — a ref manufactured from prose. Measured live: five
+ * prose cells on one board, three of them reaching `unmeasurable` under three
+ * different mis-parses. A position cannot be mis-parsed that way.
+ */
+export type CellKind = "ref" | "empty" | "prose";
+export function cellKindOf(cell: string): CellKind {
+  const s = String(cell ?? "").trim();
+  if (!s || s === "—" || s === "-" || s === "–") return "empty";
+  return /^`[^`]+`/.test(s) ? "ref" : "prose";
+}
+/** The `\`ref\`` in a `Branch · Worktree` cell's REF POSITION (leading token), or "". */
 export function refInCell(cell: string): string {
-  return (String(cell ?? "").match(/`([^`]+)`/)?.[1] ?? "").trim();
+  return (String(cell ?? "").trim().match(/^`([^`]+)`/)?.[1] ?? "").trim();
+}
+/** A display elision a human typed into a machine-read field. */
+const ELIDED = /…|\.\.\./;
+
+/*
+ * ⟨q-5d1c8e04⟩ — LANES vs ROLES. A ROLE row is a standing seat (coordinator,
+ * aide) with nothing to score: no branch, no slice, no stall. It is written with
+ * its own status glyph and a `—` branch cell, in the same table. The glyph is
+ * a bus-level ROW KIND, not a work state: the seam's `workStateOf` reads it as
+ * `unknown`, which is correct — a role is not work, and the seam is not asked
+ * to invent a state for it.
+ *
+ * ⚠ A 🪑 ROW THAT CARRIES A REF IS A LANE IN DISGUISE and is scored as one —
+ * relabelling work as a role must not exempt it from the clock.
+ */
+export const ROLE_GLYPH = "🪑";
+const STATUS_DECORATION = /^[\s*⭐]+/u;
+export const isRoleStatus = (status: string): boolean => String(status ?? "").replace(STATUS_DECORATION, "").startsWith(ROLE_GLYPH);
+export type RowKind = "lane" | "role" | "role-with-ref";
+export function rowKindOf(row: { status: string; branchWorktree: string }): RowKind {
+  if (!isRoleStatus(row.status)) return "lane";
+  return cellKindOf(row.branchWorktree) === "ref" ? "role-with-ref" : "role";
 }
 
 /** The remote-tracking form a board cell should name for `branch`. */
@@ -106,7 +158,22 @@ export function classifyBoardRef(
   base = "origin/main",
 ): BoardRefVerdict {
   const raw = refInCell(cell);
-  if (!raw) return { kind: "empty", why: "no ref in the Branch · Worktree cell" };
+  if (!raw) {
+    // Words in the ref position are a DECLARATION, not an absence: the row
+    // says it has no per-agent branch. Only a blank or `—` is "nothing said".
+    if (cellKindOf(cell) === "prose") {
+      return { kind: "none", why: `the Branch · Worktree cell declares in words that this row carries no per-agent branch: "${String(cell).trim().slice(0, 60)}"` };
+    }
+    return { kind: "empty", why: "no ref in the Branch · Worktree cell, and nothing declared in its place" };
+  }
+  if (ELIDED.test(raw)) {
+    return {
+      kind: "elided",
+      why:
+        `'${raw}' is a ref a human abbreviated for display — it contains an elision and cannot be looked up as written. ` +
+        `Unreadable by construction, not "unpushed": the real ref may well exist. Write the full ref in the cell; the note can carry the shape.`,
+    };
+  }
 
   const bare = raw.replace(/^origin\//, "");
 

package/src/tools/event-kinds.ts

@@ -17,7 +17,20 @@
  * 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 };
+/**
+ * ⟨q-2b7d9f04⟩ — EVERY KIND SHIPS WITH THE CHANGE THAT MUST PRODUCE IT. The
+ * `item` subscription sat at `health: ok` for three days while structurally
+ * unable to fire: an emitter existed, so the registry was satisfied, and the
+ * scanner RAN, so liveness was satisfied — but the grammar never read the
+ * leading item id `land` writes, so no live commit could ever produce the
+ * kind. A probe is the LIVE shape, not the smallest one: two items out, two
+ * leading-id entries in, one PR — the #328 commit. Health asks the scanner to
+ * produce each kind from its probe; a kind whose probe yields nothing CANNOT
+ * FIRE, whatever the emitter list and the scan clock say.
+ */
+export type KindProbe = { diff: string; after?: { done?: string; phases?: Record<string, string> } };
+/** `refs`: ⟨q-cbace757⟩ — a closure cited by N PRs carries all N, each checked against the record on its own; `ref` stays the joined form for the event key. */
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string; refs?: string[] };
 
 /*
  * THE KIND REGISTRY IS THE SINGLE SOURCE, AND THAT IS TASK 9.2.
@@ -37,23 +50,27 @@ export type RecordEvent = { kind: SubKind; target: string; ref: string; summary:
 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",
+    what: "a queue item closed — a DONE.md entry beginning with its ⟨q-…⟩ id appeared (land writes it), or it left QUEUE.md against one unambiguous entry",
     targetIs: "the queue item id",
+    probe: { diff: "diff --git a/docs/QUEUE.md b/docs/QUEUE.md\n--- a/docs/QUEUE.md\n+++ b/docs/QUEUE.md\n@@ -1,1 +1,1 @@\n-- [ ] (P1) ⟨q-0a0a0a01⟩ Kit: the first thing to do\n-- [ ] (P1) ⟨q-0a0a0a02⟩ Kit: the second thing to do\n\ndiff --git a/docs/DONE.md b/docs/DONE.md\n--- a/docs/DONE.md\n+++ b/docs/DONE.md\n@@ -1,1 +1,1 @@\n+- [x] ⟨q-0a0a0a01⟩ Kit: what was done for the first… — owner/repo#77 · 2026-09-14\n+- [x] ⟨q-0a0a0a02⟩ Kit: what was done for the second… — owner/repo#77 · 2026-09-14\n" } as KindProbe,
   },
   pr: {
     record: "docs/DONE.md",
     what: "a PR recorded in the completion log",
     targetIs: "the PR ref, e.g. owner/repo#163",
+    probe: { diff: "diff --git a/docs/DONE.md b/docs/DONE.md\n--- a/docs/DONE.md\n+++ b/docs/DONE.md\n@@ -1,1 +1,1 @@\n+- [x] a PR recorded in the completion log — owner/repo#78 · 2026-09-14\n" } as KindProbe,
   },
   task: {
     record: "docs/phases/**/PHASE*_TASKS.md",
     what: "a phase task checkbox newly ticked",
     targetIs: "the task key, e.g. 5:12.1",
+    probe: { diff: "diff --git a/docs/phases/phase9/PHASE9_TASKS.md b/docs/phases/phase9/PHASE9_TASKS.md\n--- a/docs/phases/phase9/PHASE9_TASKS.md\n+++ b/docs/phases/phase9/PHASE9_TASKS.md\n@@ -1,1 +1,1 @@\n-- [ ] 1.1 first\n+- [x] 1.1 first\n" } as KindProbe,
   },
   phase: {
     record: "docs/phases/**/PHASE*_TASKS.md",
     what: "the last open checkbox in a phase document ticked",
     targetIs: "the phase number, e.g. 5",
+    probe: { diff: "diff --git a/docs/phases/phase9/PHASE9_TASKS.md b/docs/phases/phase9/PHASE9_TASKS.md\n--- a/docs/phases/phase9/PHASE9_TASKS.md\n+++ b/docs/phases/phase9/PHASE9_TASKS.md\n@@ -1,1 +1,1 @@\n-- [ ] 1.2 second\n+- [x] 1.2 second\n", after: { phases: { "docs/phases/phase9/PHASE9_TASKS.md": "# Phase 9\n\n- [x] 1.1 first\n- [x] 1.2 second\n" } } } as KindProbe,
   },
 } as const;
 

package/src/tools/events.ts

@@ -78,8 +78,33 @@ function writeSubs(subs: Subscription[]): void {
  * subscription with no last-evaluated mark has produced no evidence of
  * anything, and "no events" is the same output a broken subscription gives.
  */
+/**
+ * ⟨q-2b7d9f04⟩ — CAPABILITY, NOT LIVENESS. The `item` subscription read
+ * `health: ok — no events yet` for three days while the scanner's grammar
+ * could not produce its kind from any commit: the scan clock was fresh, the
+ * emitter list had an entry, and the field answered the easier question. The
+ * probe is registered by record-events.ts (which owns the grammar) and asks
+ * "can this kind be produced at all?"; a kind that cannot is an ERROR, however
+ * recently the scanner ran. Absent probe → no claim either way.
+ */
+let capabilityProbe: ((kind: SubKind) => boolean) | null = null;
+export function setCapabilityProbe(fn: ((kind: SubKind) => boolean) | null): void {
+  capabilityProbe = fn;
+}
+export const kindCanFire = (kind: SubKind): boolean | null => (capabilityProbe ? capabilityProbe(kind) : null);
+
 export function subscriptionHealth(s: Subscription): { level: "ok" | "error" | "unknown"; detail: string } {
   const iso = (n: number) => new Date(n).toISOString();
+  // ⟨q-2b7d9f04⟩ — a kind the grammar cannot produce is not ok, scanned or not.
+  if (kindCanFire(s.kind) === false) {
+    return {
+      level: "error",
+      detail:
+        `CANNOT FIRE — the scanner's grammar produces no '${s.kind}' event from the kind's own probe, so this subscription is structurally unable to deliver ` +
+        `${s.lastScannedAt ? `(scanned ${iso(s.lastScannedAt)}: the clock is live, the capability is not)` : "(and has never been scanned)"}. ` +
+        "Never fired and cannot fire are different facts; this is the second.",
+    };
+  }
 
   // THREE STATES, BECAUSE THERE ARE THREE FACTS. They were two, and the
   // collapse cost a week: an `item` subscriber read `error — never evaluated`
@@ -152,11 +177,18 @@ export const eventKey = (kind: SubKind, target: string, ref: string): string =>
  */
 export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true } | { ok: false; error: string } {
   if (!ev.ref) return { ok: false, error: `event for ${ev.kind} ${ev.target} carries no ref — nothing ties it to a record entry` };
-  if (!String(recordText).includes(ev.ref))
+  // ⟨q-cbace757⟩ — a multi-PR closer is N citations, checked ONE BY ONE. The
+  // joined string ("a#1, a#2, a#3") is how the event is keyed, not how the record
+  // is read: a DONE line citing the same three PRs in another arrangement carries
+  // every ref and none of the joined form. The guard stays exactly as strict per
+  // ref — a citation absent from the record still refuses, and is named.
+  const refs = ev.refs?.length ? ev.refs : [ev.ref];
+  const missing = refs.filter((r) => !String(recordText).includes(r));
+  if (missing.length)
     return {
       ok: false,
       error:
-        `refusing to emit ${ev.kind} ${ev.target}: its ref ${ev.ref} is NOT in the record. ` +
+        `refusing to emit ${ev.kind} ${ev.target}: ${missing.length === refs.length && refs.length === 1 ? `its ref ${ev.ref}` : `${missing.length} of its ${refs.length} cited ref(s) — ${missing.join(", ")} —`} is NOT in the record. ` +
         `An event that exists without the record change that caused it is a second source of truth — ` +
         `the stream would claim something the authoritative document does not.`,
     };
@@ -258,10 +290,16 @@ export async function listSubscriptionsTool(args: { agentId?: string }) {
   const all = readSubs();
   const subs = args.agentId ? all.filter((s) => s.agentId === args.agentId) : all;
   const rows = subs.map((s) => ({ ...s, health: subscriptionHealth(s) }));
-  const neverEvaluated = rows.filter((r) => r.health.level === "error");
+  const cannotFire = rows.filter((r) => r.health.level === "error" && /^CANNOT FIRE/.test(r.health.detail));
+  const neverEvaluated = rows.filter((r) => r.health.level === "error" && !/^CANNOT FIRE/.test(r.health.detail));
   const undetermined = rows.filter((r) => r.health.level === "unknown");
   return {
-    ok: neverEvaluated.length === 0,
+    ok: neverEvaluated.length === 0 && cannotFire.length === 0,
+    // ⟨q-2b7d9f04⟩ — capability per kind, beside each row's liveness.
+    capability: Object.fromEntries(EVENT_KIND_IDS.map((k) => [k, kindCanFire(k)])),
+    ...(cannotFire.length
+      ? { cannotFire: `${cannotFire.length} of ${rows.length} subscription(s) are to a kind the scanner CANNOT PRODUCE — they will never fire, however live the scan clock reads: ${[...new Set(cannotFire.map((r) => r.kind))].join(", ")}.` }
+      : {}),
     // Population beside the verdict, always: "no subscriptions" and "none
     // listed for you" are different claims.
     population: { listed: rows.length, total: all.length },

package/src/tools/herdr-delivery.ts

@@ -0,0 +1,87 @@
+/**
+ * IN-PROCESS DELIVERY FOR HERDR SEATS (Phase 5.4 Task 4, box 4.4).
+ *
+ * A tmux seat has a pusher that tails its inbox and the rooms it joined, formats a batch,
+ * types it into the pane and advances the PUSH cursor once the paste is verified submitted
+ * (hooks/tmux-pusher.mjs + hooks/push-cursor.mjs). A herdr seat has no pusher, so the
+ * server does the same at SEND time: the message it just appended is formatted by the very
+ * same formatter the pusher uses (hooks/tier.mjs — one renderer, so the pane sees one
+ * shape on either transport), pushed through the transport, and ONLY on a verified
+ * delivery is the seat's push cursor advanced past it.
+ *
+ * THE CURSOR RULE IS THE PUSHER'S, UNCHANGED (⟨q-7be94b5e⟩): a paste that did not reach the
+ * pane must not mark the message consumed. The push cursor is advanced to the offset the
+ * append produced, and never touched when the transport reports not-delivered — the
+ * message stays where `read_messages` still serves it. The READ cursor is the agent's and
+ * is never written here.
+ *
+ * Simplification stated: the pusher batches routine room traffic into digests on a
+ * debounce; a herdr seat receives each message as it is sent, in the digest FORMAT (the
+ * `[agent-coord] …` banner and the attributed line) but one at a time. Tiers still decide
+ * the banner text. Batching for herdr is Task 5 territory if it is wanted.
+ */
+import { statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { activeTransport, HERDR, type TransportMarker } from "../transports/index.js";
+import { ROOT, inboxFile, roomFile } from "../store.js";
+import { loadLiveTransports } from "./registry.js";
+import type { Message } from "./shared.js";
+
+type Tier = { formatBatch: (batch: unknown[], agentId: string, rooms: string[]) => string; classifyTier: (m: unknown, opts?: unknown) => string };
+type PushCursor = { readPushCursor: (root: string, safeId: string) => Record<string, unknown>; writePushCursor: (root: string, safeId: string, c: Record<string, unknown>) => void };
+let hooks: Promise<{ tier: Tier; cursor: PushCursor }> | undefined;
+function loadHooks(): Promise<{ tier: Tier; cursor: PushCursor }> {
+  hooks ??= (async () => {
+    const base = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "..", "hooks");
+    const tier = (await import(pathToFileURL(path.join(base, "tier.mjs")).href)) as Tier;
+    const cursor = (await import(pathToFileURL(path.join(base, "push-cursor.mjs")).href)) as PushCursor;
+    return { tier, cursor };
+  })();
+  return hooks;
+}
+const safeId = (id: string) => id.replace(/[^A-Za-z0-9._-]/g, "_");
+
+export type HerdrDeliveryOutcome = { agentId: string; delivered: boolean; enters?: number; error?: string; cursorAdvanced: boolean };
+
+/** Deliver one just-appended message to every herdr-attached recipient among `recipients`. */
+export async function deliverToHerdrSeats(msg: Message, recipients: string[], where: { kind: "dm" } | { kind: "room"; chan: string }): Promise<HerdrDeliveryOutcome[]> {
+  const t = activeTransport();
+  if (!t || t.kind !== HERDR) return [];
+  let markers: Map<string, TransportMarker>;
+  try { markers = await loadLiveTransports(); } catch { return []; }
+  const out: HerdrDeliveryOutcome[] = [];
+  for (const agentId of recipients) {
+    const marker = markers.get(agentId);
+    if (!marker || marker.transport !== HERDR) continue;
+    if (where.kind === "room" && marker.rooms === false) continue;
+    if (msg.from === agentId) continue;
+    const { tier, cursor } = await loadHooks();
+    const tagged = { ...msg, tag: where.kind === "dm" ? "DM" : `room #${where.chan}` };
+    const rendered = tier.formatBatch([{ ...tagged, tier: tier.classifyTier(tagged) }], agentId, where.kind === "room" ? [where.chan] : []);
+    // A control never comes through here: send_command hands a herdr seat's control to the
+    // transport's sendControl directly (a raw-vs-rendered branch here was dead and its
+    // mutation survived, so it is gone). Everything delivered here is a rendered message.
+    let r: { delivered: boolean; error?: string; enters?: number };
+    try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, error: (e as Error).message }; }
+    let cursorAdvanced = false;
+    if (r.delivered) {
+      try {
+        const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
+        const size = statSync(file).size;
+        const id = safeId(agentId);
+        const c = cursor.readPushCursor(ROOT, id) ?? {};
+        if (where.kind === "dm") c.inboxOffset = Math.max(Number(c.inboxOffset ?? 0), size);
+        else {
+          const offsets = ((c.roomOffsets as Record<string, number> | undefined) ?? {});
+          offsets[where.chan] = Math.max(Number(offsets[where.chan] ?? 0), size);
+          c.roomOffsets = offsets;
+        }
+        cursor.writePushCursor(ROOT, id, c);
+        cursorAdvanced = true;
+      } catch { cursorAdvanced = false; }
+    }
+    out.push({ agentId, delivered: r.delivered, enters: r.enters, error: r.error, cursorAdvanced });
+  }
+  return out;
+}

package/src/tools/messaging.ts

@@ -13,6 +13,7 @@ import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { checkClosingLine } from "../closing-line.js";
 import { readLog } from "./logwatch.js";
 // The replay grammar is single-sourced in hooks/replay.mjs and shared with both
 // pushers — see the note at the annotation site below. `hooks/` ships beside
@@ -82,6 +83,9 @@ import {
   MAX_WAIT_MS,
   isDecision,
 } from "./shared.js";
+import { isKnownHuman } from "../store.js";
+import { deliverToHerdrSeats } from "./herdr-delivery.js";
+import { verifyCommitCite } from "../commit-cite.js";
 
 // ---------- send_message ----------
 
@@ -110,10 +114,18 @@ const decisionPayload = z.looseObject({
   ifNoAction: z.string().min(1),
 });
 
+// ⟨q-dcbaf544⟩ — `gatedBy` is the seat that JUDGED when it is not the sender;
+// `scribe` is the sender that TRANSCRIBED it. Fields, not prose: a name in
+// prose is a mention, a name in a field is a position, and only the position
+// survives a scanner. Authority does not move (David's ruling 2026-09-14):
+// the roles that may emit `verdict` are unchanged; this is how a gate routed
+// to any other seat reaches the record without lying about who gated.
 const verdictPayload = z.looseObject({
   result: z.enum(["pass", "fail"]),
   headRefOid: z.string().min(1),
   notes: z.string().optional(),
+  gatedBy: z.string().min(1).optional(),
+  scribe: z.string().min(1).optional(),
 });
 
 // Discriminated on `type`, so an unknown type is rejected outright while a
@@ -170,6 +182,21 @@ export async function checkRecordAuthority(
   };
 }
 
+/** ⟨q-dcbaf544⟩ — `scribe`, when present, must be the sender; `gatedBy` may name anyone (that is its point). */
+export function checkVerdictScribe(from: string, record: MessageRecord | undefined): { ok: true } | { ok: false; error: string } {
+  if (!record || record.type !== "verdict") return { ok: true };
+  const p = record.payload as { scribe?: string; gatedBy?: string } | undefined;
+  if (p?.scribe && p.scribe !== from) {
+    return {
+      ok: false,
+      error:
+        `verdict payload.scribe is '${p.scribe}' but the sender is '${from}' — the scribe is the seat that SENDS the record. ` +
+        `Put the seat that judged in payload.gatedBy and either omit scribe or set it to '${from}'.`,
+    };
+  }
+  return { ok: true };
+}
+
 // ---------- typed records obligatory (Phase 5.1 Task 12) ----------
 
 // An untyped agent→agent message must not be able to EXIST. Enforced HERE, at
@@ -202,7 +229,10 @@ async function typedRecordCheck(args: {
   // 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 };
+  // ⟨q-178878aa⟩ — and the human need not be a REGISTERED agent: a registry entry for a
+  // human is evicted after EVICT_MS (no heartbeat), so the exemption keys on the durable
+  // human set the server knows (humans.json + AGENT_COORD_HUMANS), read here, at send time.
+  if (args.to && (isHuman(reg[args.to]) || (await isKnownHuman(args.to)))) return { ok: true };
 
   const sender = reg[args.from];
   if (sender?.proseOnly) return { ok: true };
@@ -227,7 +257,8 @@ async function typedRecordCheck(args: {
       `${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.`,
+      `Messages TO a human are exempt (a recipient registered with a human role, or an id the server knows as human: ` +
+      `humans.json / AGENT_COORD_HUMANS — see list_agents.humans), and an agent that cannot pick a type declares proseOnly:true at join.`,
   };
 }
 
@@ -245,6 +276,9 @@ export const sendMessageSchema = {
   // unknown → store + warn) so the rejection shape matches identity-binding
   // / unknown-recipient, not a schema throw. Existing records unchanged.
   inReplyTo: z.string().optional(),
+  // ⟨q-cc0819dc⟩ — needed only for a `done` cited by COMMIT: the repository whose
+  // origin/main must carry the sha (one local git call, no network).
+  repo: z.string().optional(),
 };
 
 const MESSAGE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -298,25 +332,47 @@ export async function sendMessageTool(args: {
   kind?: "decision" | "status" | "chatter";
   record?: MessageRecord;
   inReplyTo?: string;
+  repo?: string;
 }) {
   // Record authority first — a sender who may not emit this type is refused
   // before any other check runs, so a rejected record writes nothing anywhere.
   const authority = await checkRecordAuthority(args.from, args.record);
   if (!authority.ok) return { ok: false as const, error: authority.error };
+  // ⟨q-dcbaf544⟩ — a scribe is the sender by definition; a verdict whose
+  // `scribe` names someone else has its two positions crossed and would be
+  // attributed wrongly by every reader. Refused as a value, nothing written.
+  const scribeCheck = checkVerdictScribe(args.from, args.record);
+  if (!scribeCheck.ok) return { ok: false as const, error: scribeCheck.error };
 
   // A `done` must cite the work it claims. Presence and shape only — resolving
   // the ref against gh/git is a consumer's job, and the send path makes no
   // network calls. Rejected as a value, not a throw, mirroring the
   // identity-binding rejection in src/server.ts.
   if (args.record?.type === "done") {
-    const hasPr = (args.record.cites ?? []).some((c) => c.kind === "pr" && c.ref.trim().length > 0);
-    if (!hasPr) {
+    // ⟨q-fee7239f⟩ — the same check that reads the closing citation reads the
+    // closing GRAMMAR: a merge closing may not assert a deletion it has not
+    // read. Refused as a value, naming the two accepted forms; nothing written.
+    const closing = checkClosingLine(String(args.text ?? ""));
+    if (!closing.ok) return { ok: false as const, error: closing.error };
+    const cites = args.record.cites ?? [];
+    const hasPr = cites.some((c) => c.kind === "pr" && c.ref.trim().length > 0);
+    const commitCites = cites.filter((c) => c.kind === "commit");
+    if (!hasPr && commitCites.length === 0) {
       return {
         ok: false as const,
         error:
-          "a 'done' record must carry at least one {kind:'pr'} citation — an uncited DONE is an unverifiable claim",
+          "a 'done' record must carry at least one {kind:'pr'} citation — an uncited DONE is an unverifiable claim. " +
+          "Work that has no PR by rule (docs pushed straight to the shared branch) cites {kind:'commit', ref:<full 40-hex sha>} " +
+          "and passes `repo`, the repository whose origin/main carries it.",
       };
     }
+    // ⟨q-cc0819dc⟩ — a COMMIT cite satisfies a `done` only when the commit is real and on the
+    // shared branch: every commit cite is verified, so a fabricated or short sha is refused
+    // by name and nothing is written. A PR cite beside it does not excuse a bad commit cite.
+    for (const c of commitCites) {
+      const v = verifyCommitCite(c.ref, args.repo);
+      if (!v.ok) return { ok: false as const, error: `a 'done' record cited by commit was refused — ${v.why}` };
+    }
   }
 
   // `text` is what every consumer reads, so it must exist. The author's
@@ -399,13 +455,18 @@ export async function sendMessageTool(args: {
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
+    // Phase 5.4 Task 4 — a herdr-attached recipient has no pusher: deliver now, in-process.
+    const herdr = await deliverToHerdrSeats(msg, [args.to], { kind: "dm" });
+    void herdr;
     // Offline delivery is intentional (the inbox is created on demand), but a
     // typo'd recipient shouldn't vanish silently — surface a warning when the
     // target isn't a known agent so the caller can catch the mistake.
     const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
     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`;
+      : (await isKnownHuman(args.to))
+        ? undefined // a human is not an agent and is not expected to be registered; the inbox is theirs to read
+        : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
     const warning = [typedWarning, recipientWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
     return { ok: true, id: msg.id, target, room: undefined, warning };
   }
@@ -425,6 +486,10 @@ export async function sendMessageTool(args: {
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
+  // Phase 5.4 Task 4 — herdr-attached members with rooms on receive the post now, in-process.
+  const roomMembers = (await getRooms())[chan]?.members ?? [];
+  const herdrRoom = await deliverToHerdrSeats(msg, roomMembers, { kind: "room", chan });
+  void herdrRoom;
   await maybeCompactRoom(chan);
   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

@@ -159,8 +159,28 @@ export function eventsFromCommittedChange(
   // 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");
+  // ⟨q-d527f435⟩ — A REMOVED LINE IS NOT A DEPARTED ITEM. The scan diffed text,
+  // so the aide's in-place rewrite of q-a1c9d4e7 (70c730a) read as a departure
+  // and was reported unattributed. The question is whether the ⟨q-…⟩ id is
+  // still present at the end of the range; three cases, never conflated:
+  //   id still present in the ADDED lines  → an EDIT — no event, not unattributed
+  //   id absent                            → a DEPARTURE — attributed or reported
+  //   id CHANGED (same text, new id)       → a RE-ID — reported as such (⟨q-1c4f8ae3⟩)
+  const addedQueue = linesWhere(byFile, isQueue, "added");
+  // Only rows still OPEN count as present: the house style closes an item by
+  // flipping `[ ]` → `[x]` in place, and that row is closed, not edited.
+  const addedItems = (queueItemsOf(parseWorkDoc(`## Queue\n${addedQueue.join("\n")}\n`)) as Array<{ id?: string; text?: string; done?: boolean }>).filter((i) => i.id && !i.done);
+  const addedIds = new Set(addedItems.map((i) => i.id!));
+  const reIdentified: { from: string; to: string }[] = [];
   const removedItems = (queueItemsOf(parseWorkDoc(`## Queue\n${removedQueue.join("\n")}\n`)) as Array<{ id?: string; text?: string }>)
-    .filter((i) => i.id);
+    .filter((i) => i.id)
+    .filter((i) => {
+      if (addedIds.has(i.id!)) return false; // edited in place: still on the queue
+      const twin = addedItems.find((a) => a.id !== i.id && norm(a.text ?? "") === norm(i.text ?? "") && norm(i.text ?? ""));
+      if (twin) { reIdentified.push({ from: i.id!, to: twin.id! }); return false; }
+      return true;
+    });
+  lastReIdentifiedItems = reIdentified;
   // An entry qualifies to CLOSE an item if it cites anything resolvable — a PR,
   // or an `@sha` commit. `land` requires a PR by rule; the scan reads what the
   // record actually says, and a commit-cited entry is still the record stating
@@ -168,7 +188,24 @@ export function eventsFromCommittedChange(
   const citedEntries = newEntries.filter((e) => prRefsIn(e.ref).length > 0 || hasCommitRef(e.ref ?? ""));
   const unattributed: string[] = [];
 
+  // ⟨q-2b7d9f04⟩ — THE LINK THE MARKDOWN DOES CARRY. `land` writes the item's
+  // id in LEADING position on the DONE line (#286), and a hand-written line in
+  // land's format carries it the same way. An entry that begins with ⟨q-…⟩ IS
+  // the record of that item closing — read by position, never guessed. The
+  // `item` subscription never fired in three days because this read was
+  // missing while the paragraph above said no link existed.
+  const attributedByLeadingId = new Set<string>();
+  for (const entry of citedEntries) {
+    const id = leadingItemIdOf(entry.text);
+    if (!id || attributedByLeadingId.has(id)) continue;
+    const ref = prRefsIn(entry.ref)[0] ?? entry.ref?.trim();
+    if (!ref) continue;
+    attributedByLeadingId.add(id);
+    events.push({ kind: "item", target: id, ref, summary: entry.text?.slice(0, 120) ?? id });
+  }
+
   for (const item of removedItems) {
+    if (attributedByLeadingId.has(item.id!)) continue;
     const itemText = norm(item.text ?? "");
     let entry = itemText
       ? citedEntries.find((e) => {
@@ -241,6 +278,36 @@ export function eventsFromCommittedChange(
  * different facts, and only one of them needs a human.
  */
 export let lastUnattributedItems: string[] = [];
+/** ⟨q-d527f435⟩ — removed rows whose TEXT reappeared under a NEW id in the same change: re-identified, not departed. */
+export let lastReIdentifiedItems: { from: string; to: string }[] = [];
+/** ⟨q-2b7d9f04⟩ — the ⟨q-…⟩ id in LEADING position on a DONE entry's text (bold allowed), or null. Position, not occurrence: an id quoted mid-sentence is a mention. */
+export function leadingItemIdOf(text: string | undefined): string | null {
+  const m = /^\s*(?:\*\*)?⟨(q-[0-9a-f]{8})⟩/.exec(String(text ?? ""));
+  return m ? m[1]! : null;
+}
+/**
+ * ⟨q-2b7d9f04⟩ — CAN THIS KIND FIRE AT ALL? Runs the scanner over the kind's
+ * own probe (event-kinds.ts) and asks whether an event of that kind comes out.
+ * Health reads this as CAPABILITY, beside the scan clock's LIVENESS: a kind
+ * whose probe yields nothing cannot be produced by the grammar, and a
+ * subscription to it is not `ok` however recently the scanner ran.
+ */
+export function kindCapability(kind: SubKind): { capable: boolean; produced: number; why: string } {
+  const probe = (EVENT_KINDS[kind] as { probe?: { diff: string; after?: { done?: string; phases?: Record<string, string> } } }).probe;
+  if (!probe) return { capable: false, produced: 0, why: `'${kind}' ships no probe — its capability cannot be shown` };
+  const saved = lastUnattributedItems;
+  let produced = 0;
+  try {
+    produced = eventsFromCommittedChange(probe.diff, probe.after ?? {}).filter((e) => e.kind === kind).length;
+  } finally {
+    lastUnattributedItems = saved;
+  }
+  return produced > 0
+    ? { capable: true, produced, why: `the scanner produced ${produced} '${kind}' event(s) from the kind's own probe` }
+    : { capable: false, produced: 0, why: `the scanner produced NO '${kind}' event from the kind's own probe — this kind CANNOT FIRE on any commit, whatever the scan clock says` };
+}
+export const kindCapabilities = (): Record<SubKind, ReturnType<typeof kindCapability>> =>
+  Object.fromEntries((Object.keys(EVENT_KINDS) as SubKind[]).map((k) => [k, kindCapability(k)])) as Record<SubKind, ReturnType<typeof kindCapability>>;
 
 /** `git` in a repo, returning "" rather than throwing — a scan is read-only. */
 export function git(repo: string, args: string[]): string {
@@ -257,7 +324,9 @@ 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, markScanned } from "./events.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived, markScanned, setCapabilityProbe } from "./events.js";
+// ⟨q-2b7d9f04⟩ — health consults the scanner's grammar through this hook (events.ts cannot import this module: the kinds are its leaf and record-events imports events).
+setCapabilityProbe((kind) => kindCapability(kind).capable);
 
 /**
  * The watermark: the last commit whose record change has been turned into
@@ -333,6 +402,7 @@ export async function scanRecordEventsTool(args: { repo: string; since?: string;
 
   const candidates = eventsFromCommittedChange(diff, { done: doneText, phases });
   const unattributed = [...lastUnattributedItems];
+  const reIdentified = [...lastReIdentifiedItems];
 
   // 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
@@ -378,11 +448,14 @@ export async function scanRecordEventsTool(args: { repo: string; since?: string;
       ? {
           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.`,
+            `${unattributed.length} queue item(s) left docs/QUEUE.md in this range with NO done entry carrying their id in leading position ` +
+            `(\`- [x] ⟨q-…⟩ …\`, the form land writes) and no unambiguous pairing. They emitted NOTHING rather than a guess: a DONE line ` +
+            `without a leading id names no item. "Closed by an unknown entry" and "not closed" are different facts and this is the first.`,
         }
       : {}),
+    ...(reIdentified.length
+      ? { reIdentifiedItems: reIdentified, reIdentifiedNote: `${reIdentified.length} queue row(s) reappeared under a NEW id with the same text — re-identified, neither departed nor closed (⟨q-1c4f8ae3⟩'s subject).` }
+      : {}),
     ...(args.write
       ? { watermark: head }
       : {