agent-coord-mcp 0.26.21 → 0.26.22

package/src/tools/away.ts

@@ -75,7 +75,46 @@ export const PARKED_CATEGORIES = [
   "destructive machine actions",
 ] as const;
 
-export type AwayCoverage = { checked: number; measurable: number; blind: string[]; at: string };
+/*
+ * ⟨q-5a71fc3b⟩ — THE THRESHOLD, NAMED. `coord_away` armed a fleet that was 3/5
+ * blind, silently: the refusal only fired at ZERO measurable lanes, so "2 of
+ * 5" — three seats the clock could not see — read as covered enough. A
+ * partially blind fleet IS the incident, not a lesser case of it: the seats
+ * nobody can see are exactly the ones an absence leaves unattended. So the
+ * threshold is every in-flight lane the clock scores, the refusal names the
+ * seats short of it, and `acknowledgeBlindFleet` is the only way past.
+ */
+export const COVERAGE_THRESHOLD = "EVERY in-flight lane the clock scores must be measurable";
+/*
+ * ⟨q-ce585029⟩ — A QUERY REPORTS THE COVERAGE MEASURED AT ARM TIME, AND SAYS
+ * SO. "Coverage 2/5" read on 09-11 was three days old by the time it was
+ * quoted as current. The query stays free (no re-measure); the summary
+ * carries the reading's age and labels it stale past this many minutes.
+ */
+export const COVERAGE_STALE_MINUTES = 60;
+export const fmtAge = (ms: number): string => (ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m` : ms < 86_400_000 ? `${Math.floor(ms / 3_600_000)}h` : `${Math.floor(ms / 86_400_000)}d`);
+export function coverageAgeOf(coverage: { at: string }, now = Date.now()): { ageMs: number | null; stale: boolean; label: string } {
+  const at = Date.parse(coverage.at);
+  if (!Number.isFinite(at)) return { ageMs: null, stale: true, label: "measured at an unreadable time — treat as stale" };
+  const ageMs = Math.max(0, now - at);
+  const stale = ageMs > COVERAGE_STALE_MINUTES * 60_000;
+  return { ageMs, stale, label: `measured ${fmtAge(ageMs)} ago${stale ? ` — STALE (older than ${COVERAGE_STALE_MINUTES}m; re-arm or run stall_check for a current reading)` : ""}` };
+}
+/** Met when nothing scored is unseen — an empty board (0 of 0) is idle, not blind, and needs no special case. */
+export const meetsCoverageThreshold = (c: { checked: number; measurable: number }): boolean => c.measurable >= c.checked;
+
+export type AwayCoverage = {
+  checked: number;
+  measurable: number;
+  blind: string[];
+  /** ⟨q-5d1c8e04⟩ — standing seats on the board: present, not scored, and therefore not blind. */
+  roles?: number;
+  /** Lanes that declare no per-agent branch: out of the population by their own statement. */
+  deliberate?: number;
+  /** ⟨q-3d82f1a9⟩ — the board could not be read: rows present vs parsed, as stall_check stated it. */
+  unreadable?: { rowsPresent: number; rowsParsed: number; why: string };
+  at: string;
+};
 
 export type AwayState = {
   on: boolean;
@@ -180,10 +219,28 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
   if (!repo) return null;
   try {
     const r = (await stallCheckTool({ repo })) as unknown as {
-      ok?: boolean; checked?: number; measurable?: number; blind?: string[];
+      ok?: boolean; checked?: number; measurable?: number; blind?: string[]; roles?: unknown[]; deliberate?: unknown[];
+      boardParse?: { readable: boolean; rowsPresent: number; rowsParsed: number; why: string };
     };
+    // ⟨q-3d82f1a9⟩ — AN UNREADABLE BOARD IS A NAMED STATE, not "could not measure".
+    // The clock refused to answer because the board broke; arming on it would
+    // promise a watched fleet over a table nobody can read.
+    if (r?.boardParse && !r.boardParse.readable) {
+      return {
+        checked: 0, measurable: 0, blind: [], roles: 0, deliberate: 0,
+        unreadable: { rowsPresent: r.boardParse.rowsPresent, rowsParsed: r.boardParse.rowsParsed, why: r.boardParse.why },
+        at: new Date().toISOString(),
+      };
+    }
     if (!r?.ok) return null;
-    return { checked: r.checked ?? 0, measurable: r.measurable ?? 0, blind: r.blind ?? [], at: new Date().toISOString() };
+    return {
+      checked: r.checked ?? 0,
+      measurable: r.measurable ?? 0,
+      blind: r.blind ?? [],
+      roles: r.roles?.length ?? 0,
+      deliberate: r.deliberate?.length ?? 0,
+      at: new Date().toISOString(),
+    };
   } catch {
     return null;
   }
@@ -225,10 +282,12 @@ export async function coordAwayTool(args: {
       project: args.project,
       armed: true,
       state: prior,
+      coverageAge: coverageAgeOf(prior.coverage),
       summary:
         `'${args.project}' is ARMED — '${prior.leadId}' leads since ${prior.at}` +
         `${prior.until ? ` until ${prior.until}` : ""}. ` +
-        `Coverage ${prior.coverage.measurable}/${prior.coverage.checked}` +
+        `Coverage ${prior.coverage.measurable}/${prior.coverage.checked} lane(s) ${coverageAgeOf(prior.coverage).label}` +
+        `${prior.coverage.roles ? ` · ${prior.coverage.roles} role(s) present, not scored` : ""}` +
         `${prior.blindAcknowledged ? " (ACKNOWLEDGED BLIND)" : ""}. ` +
         `Decisions logged to ${prior.decisionLog}.`,
     };
@@ -265,17 +324,31 @@ export async function coordAwayTool(args: {
           `record that the promise is being made anyway.`,
       };
     }
+    // ⟨q-3d82f1a9⟩ — REFUSED OUTRIGHT, and not acknowledgeable: a blind fleet is
+    // one the clock can see and cannot measure; an unreadable board is one the
+    // clock cannot even see. "0 of 0" here is not idle, and no flag makes it so.
+    if (coverage.unreadable) {
+      return {
+        ok: false as const,
+        error:
+          `REFUSING: docs/WORKSTREAMS.md is UNREADABLE — ${coverage.unreadable.rowsPresent} row(s) present in the Active Streams table, ` +
+          `${coverage.unreadable.rowsParsed} parsed. ${coverage.unreadable.why} ` +
+          `Away mode promises a watched fleet; a board the clock cannot read is not a quiet fleet, it is an unwatched one. Fix the row and re-arm.`,
+      };
+    }
     // `checked > 0` MATTERS: an empty board is an IDLE fleet, not a blind one.
     // Without it, arming while nothing is in flight refuses with "the clock
     // covers 0 of 0" — a refusal that reads as a fleet nobody can see when in
     // fact there is nothing to see, and the only way past it would be to
     // acknowledge a blindness that does not exist.
-    if (coverage.checked > 0 && coverage.measurable === 0 && !args.acknowledgeBlindFleet) {
+    // ⟨q-5a71fc3b⟩ — below the threshold, not only at zero: "2 of 5" refuses.
+    if (!meetsCoverageThreshold(coverage) && !args.acknowledgeBlindFleet) {
       return {
         ok: false as const,
         error:
-          `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.checked} in-flight row(s). ` +
-          `It would RUN and see nothing${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}. ` +
+          `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.checked} in-flight row(s); the threshold is that ${COVERAGE_THRESHOLD} ` +
+          `(${coverage.checked - coverage.measurable} short)${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}. ` +
+          `${coverage.measurable === 0 ? "It would RUN and see nothing. " : "The seats it cannot see are exactly the ones an absence leaves unattended. "}` +
           `"The clock ran" and "the fleet is observed" are different facts, and this verb must not treat the first as the second. ` +
           `The usual cause is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref: a path resolves for ` +
           `git and measures the wrong thing, so the check reports it unmeasurable rather than guessing. Fix those cells and ` +
@@ -292,7 +365,7 @@ export async function coordAwayTool(args: {
       at: new Date().toISOString(),
       decisionLog: args.decisionLog,
       coverage,
-      ...(coverage.checked > 0 && coverage.measurable === 0 ? { blindAcknowledged: true } : {}),
+      ...(!meetsCoverageThreshold(coverage) ? { blindAcknowledged: true } : {}),
     };
     writeAway(state);
     return {
@@ -309,7 +382,7 @@ export async function coordAwayTool(args: {
         `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
         `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
         `Decisions logged to ${args.decisionLog}. ` +
-        `Stall coverage ${coverage.measurable}/${coverage.checked}${coverage.checked > 0 && coverage.measurable === 0 ? " — ACKNOWLEDGED BLIND: the clock runs and sees nothing" : ""}.`,
+        `Stall coverage ${coverage.measurable}/${coverage.checked}${!meetsCoverageThreshold(coverage) ? ` — ACKNOWLEDGED BLIND${coverage.measurable === 0 ? ": the clock runs and sees nothing" : ""}${coverage.blind.length ? ` on: ${coverage.blind.join(", ")}` : ""}` : ""}.`,
     };
   }
 

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,6 +17,18 @@
  * widen without adding an emitter in the same file.
  */
 export type SubKind = keyof typeof EVENT_KINDS;
+/**
+ * ⟨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> } };
 export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
 
 /*
@@ -37,23 +49,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`
@@ -258,10 +283,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/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,8 @@ import {
   MAX_WAIT_MS,
   isDecision,
 } from "./shared.js";
+import { isKnownHuman } from "../store.js";
+import { verifyCommitCite } from "../commit-cite.js";
 
 // ---------- send_message ----------
 
@@ -110,10 +113,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 +181,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 +228,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 +256,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 +275,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 +331,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
@@ -405,7 +460,9 @@ export async function sendMessageTool(args: {
     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 };
   }

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 }
       : {