agent-coord-mcp 0.26.16 → 0.26.18

package/src/tools/messaging.ts

@@ -14,6 +14,11 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 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
+// `dist/`, so this resolves the same in the built package as in source.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { priorDeliveries, replayInfo } from "../../hooks/replay.mjs";
 import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
@@ -270,6 +275,21 @@ async function messageIdExists(id: string): Promise<boolean> {
   return false;
 }
 
+// q-314e0187: `process.pid` is this MCP process's own pid — the process
+// writing the entry right now, always known, no lookup needed. It is what a
+// disputed message can be cross-referenced against (sessions/*.json,
+// `ps -p <pid>`) when two live sessions hold one identity. In stdio mode this
+// pid uniquely identifies the session (one process per session); in HTTP mode
+// many sessions can share a process, so it identifies the SERVER handling the
+// call rather than the caller — still strictly more than nothing, and the
+// same scoping `trackSession` already applies to session markers.
+function messageProvenance(): { pid: number; tmuxPane?: string } {
+  return {
+    pid: process.pid,
+    ...(process.env.TMUX_PANE ? { tmuxPane: process.env.TMUX_PANE } : {}),
+  };
+}
+
 export async function sendMessageTool(args: {
   from: string;
   to?: string;
@@ -375,6 +395,7 @@ export async function sendMessageTool(args: {
       text,
       ...(args.record ? { record: args.record } : {}),
       ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
+      provenance: messageProvenance(),
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
@@ -400,6 +421,7 @@ export async function sendMessageTool(args: {
     ...(args.kind ? { kind: args.kind } : {}),
     ...(args.record ? { record: args.record } : {}),
     ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
+    provenance: messageProvenance(),
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
@@ -540,11 +562,30 @@ export async function readMessagesTool(args: {
       ? recent.filter((e) => entryAuthor(e) !== args.agentId)
       : recent;
 
+  // Phase 5.3 Task 21.2 — ANNOTATE A MESSAGE THAT HAS ALREADY BEEN DELIVERED.
+  //
+  // The REMOTE pusher (scripts/coord-pusher.mjs) consumes the bus over the wire
+  // and cannot read this host's receipts/, so it cannot see for itself that a
+  // message it is about to paste was pasted before. Without this, the replay
+  // marker would appear in local panes only — HALF THE FLEET, and the half a
+  // reader could not identify from inside the pane, which is worse than no
+  // marker because its absence would read as "live".
+  //
+  // The two routes compute the same DATA and share ONE renderer
+  // (hooks/replay.mjs `replayMarker`), so neither pane can be handed a
+  // different vocabulary for the same fact.
+  const priorText = await fsp.readFile(receiptFile(args.agentId), "utf8").catch(() => "");
+  const prior = priorDeliveries(priorText);
+  const annotated = visible.map((e) => {
+    const replay = "id" in e ? replayInfo(prior, (e as Message).id) : undefined;
+    return replay ? { ...e, replay } : e;
+  });
+
   return {
     ok: true,
-    messages: visible,
+    messages: annotated,
     totalNew,
-    returned: visible.length,
+    returned: annotated.length,
     room: args.source === "room" ? normalizeRoom(args.room) : undefined,
     ...(history ? { history } : {}),
   };

package/src/tools/records.ts

@@ -18,17 +18,24 @@ import { z } from "zod";
 import {
   parseWorkDoc,
   renderWorkDoc,
+  renderWorkDocForWrite,
   queueItemsOf,
   doneEntriesOf,
   type QueueItem,
   type WorkDoc,
-  phaseCitationsIn,
+  phaseCitationsDetailed,
   newlyTickedInDiff,
   sweepTagOf,
+  awaitingOf,
+  refsIn,
+  refsMatch,
+  workstreamsV1RowsOf,
+  type WorkstreamsV1Row,
+  type DoneEntry,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
-import { boardRefFor } from "./board-ref.js";
-import { haltState } from "./stall.js";
+import { boardRefFor, classifyBoardRef } from "./board-ref.js";
+import { haltState, isInFlightStatus } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
@@ -51,11 +58,23 @@ const readDoc = (repo: string, rel: string): { text: string; doc: WorkDoc } | nu
  * was built, not assumed). Re-rendering an untouched file would still be a write,
  * and a write is a diff someone has to review — so the no-op case returns false.
  */
-function writeDoc(repo: string, rel: string, doc: WorkDoc, original: string): boolean {
-  const out = renderWorkDoc(doc);
-  if (out === original) return false;
-  writeFileSync(path.join(repo, rel), out);
-  return true;
+/**
+ * EVERY SUPPORTED WRITE OF A WORK DOC GOES THROUGH HERE, and it stamps.
+ *
+ * `renderWorkDocForWrite` records identity for any queue item that lacks it,
+ * including rows this caller did not author (q-c50e9b83) — the absorbed raw
+ * append is exactly the case, and stamping only the caller's own rows would keep
+ * the defect and move the blame. Every id written is the one the item already
+ * has, so nothing changes value.
+ *
+ * Returns what it stamped so the caller can report it rather than leaving an
+ * absorbing writer to find it in a diff.
+ */
+function writeDoc(repo: string, rel: string, doc: WorkDoc, original: string): { written: boolean; stamped: string[] } {
+  const { text, stamped } = renderWorkDocForWrite(doc);
+  if (text === original) return { written: false, stamped: [] };
+  writeFileSync(path.join(repo, rel), text);
+  return { written: true, stamped };
 }
 
 const git = (repo: string, args: string[]): string =>
@@ -67,6 +86,25 @@ function prNumber(pr: string): string | null {
   return m ? (m[1] as string) : null;
 }
 
+/**
+ * The `owner/repo` a BARE `#N` in this repo's docs should be read as naming —
+ * the same derivation `groundwork doctor` makes (`originRepoOf`) before it ties
+ * a closed item's citation to DONE.md. `land` must decide "already cited" with
+ * the SAME rule the auditor will apply, or the two disagree again one level
+ * down: a bare `#77` in an item body is a tie for doctor only when the origin
+ * URL says which repo, and it is a tie here under exactly that condition.
+ * Null (no remote, not a repo) means an unknown context, never a guessed one.
+ */
+function originRepoOf(repo: string): string | null {
+  try {
+    const url = git(repo, ["remote", "get-url", "origin"]);
+    const m = /[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(url);
+    return m ? (m[1] as string) : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------- blocked / no-downstream ----------
 
 const BLOCKED_RE = /\bblocked (?:by|on)\b[:\s]*([^\s·,.;]+)/i;
@@ -127,6 +165,117 @@ export function noDownstream(items: QueueItem[]): QueueItem[] {
   });
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+ * DELIVERED — READ THE RECORD'S STRUCTURE, NOT A SUBSTRING OF THE FILE.
+ *
+ * This was `doneText.includes(id) || boardText.includes(id)` over two whole
+ * documents, so ANY MENTION ANYWHERE counted as "handed out" — including a row
+ * written specifically to warn that an item must NOT be built (q-2ba7f0c5).
+ * The inversion is the finding: the more carefully a coordinator documents why
+ * something must not be routed, the more completely it disappears from the verb
+ * that routes.
+ *
+ * MEASURED ON `origin/main` @17b72ff, and the numbers moved the fix twice:
+ *
+ *   q-11257590  hidden by the AIDE'S OWN `🚧 In Progress` ROW, which merely
+ *               MENTIONS it in its Last note. A status-only rule leaves it
+ *               hidden — the occurrence-vs-position defect one level in — so
+ *               identification has to be the row's SUBJECT, not any of its cells.
+ *   q-ad0fc8d4  hidden by its own `⏸ Returned to the aide unbuilt` row.
+ *   q-507e80c4  hidden with NO PARSED ROW AT ALL: the id sits in board prose
+ *               outside the table, which a whole-file substring test cannot
+ *               distinguish from a lane.
+ *   q-507e80c4  ALSO hidden by a DONE entry that CITES it as the still-open
+ *               part (b) of work whose part (a) landed — the canon case
+ *               q-912a67e8 requires, LIVE today rather than latent.
+ *
+ * Neither half is fixed by relabelling a row: that is satisfying a guard by
+ * editing what it reads (q-507e80c4 constraint 1) and it would destroy the
+ * warning the row exists to give.
+ */
+
+/** The ids a board row names as ITS OWN SUBJECT — the Stream cell only. */
+function rowSubjectIds(row: WorkstreamsV1Row): string[] {
+  return [...String(row.stream).matchAll(/\b(q-[0-9a-f]{8})\b/g)].map((m) => m[1] as string);
+}
+
+/**
+ * Does the board show this item as IN SOMEBODY'S HANDS?
+ *
+ * Two conditions, and both are needed — measured, not reasoned:
+ *   STATUS  the row is in flight (`isInFlightStatus`, shared with `stall_check`
+ *           since #219 rather than a second glyph list). `⏸ Parked`,
+ *           `⏸ Returned`, `⏳ Queued`, `⛔ Blocked`, `🚫 Unstaffable`,
+ *           `🔻 Orphaned` describe work nobody holds, so they do not silence.
+ *   SUBJECT the row's Stream cell names the item — by recorded id, or by the
+ *           text prefix `claim` has always written there. A mention in a Last
+ *           note is one lane REFERRING to another item — the aide's live row
+ *           does exactly this — and a status-only rule would still hide it.
+ *
+ * THE PREFIX ARM IS FOR THE ROWS ALREADY ON THE BOARD, and without it this fix
+ * would have shipped a transitional hole in its own negative control: every row
+ * `claim` wrote before this change carries `keyOf(item)` — a 60-character text
+ * prefix — and no id at all, so an id-only rule leaves a lane's OWN live item
+ * routable. Measured: q-2ba7f0c5's row, written minutes earlier by the
+ * pre-merge server, was offered back while it was in hand. Rows written from
+ * here carry the id (see `claim`), so the prefix arm is the compatibility half
+ * rather than the mechanism, and it is deliberately still SUBJECT-only.
+ */
+function boardHoldsItem(rows: WorkstreamsV1Row[], id: string, text: string): boolean {
+  const key = keyOf({ text } as QueueItem).replace(/\s+/g, " ").trim();
+  return rows.some((r) => {
+    if (!isInFlightStatus(r.status)) return false;
+    if (rowSubjectIds(r).includes(id)) return true;
+    const stream = String(r.stream).replace(/\s+/g, " ").trim();
+    return key.length >= 20 && stream.startsWith(key.slice(0, Math.min(key.length, 60)));
+  });
+}
+
+/**
+ * Is this DONE entry the RECORD OF THIS ITEM CLOSING, rather than an entry that
+ * merely MENTIONS it?
+ *
+ * `DONE.md` has no status cells, so the board's answer does not transfer and
+ * this needs its own — and the item's own words for what it needs are that "the
+ * canon rule must name its citations in a form the join can tell apart".
+ *
+ * MEASURED ON THE REAL `DONE.md` @17b72ff, which settles which form is which:
+ * BRACKETED ids appear ZERO times; all ELEVEN id mentions are BARE, in prose,
+ * inside backticks — every one of them a citation. So:
+ *
+ *   DELIVERY  the entry carries the item's own COMPOSED SUMMARY — the
+ *             deterministic form `land` writes, `summarize(item.text)` — or it
+ *             names the item in the recorded-id sigil `⟨id⟩`, which is this
+ *             corpus's "this IS that item" marker (it is how QUEUE.md records
+ *             identity, and a human writing it in DONE.md means exactly that).
+ *   CITATION  a BARE `q-xxxxxxxx` anywhere. This is the form our own shipped
+ *             canon (q-912a67e8) produces: a `DONE` entry may name a residual
+ *             gap but MUST CITE A QUEUE ITEM for it. Obeying that rule wrote an
+ *             open item's id into `DONE.md`, and the substring join read the
+ *             citation as delivery — a canon rule and a code path in direct
+ *             contradiction, where COMPLIANCE with the canon triggered the
+ *             defect. LIVE on origin/main, not latent: the part (a) entry for
+ *             q-507e80c4 cites it exactly this way while part (b) is open work.
+ *
+ * Note what is deliberately NOT the rule: a shared PR ref. `land` never writes
+ * the item id into `DONE.md` at all (the summary excludes the `⟨id⟩` token), and
+ * the live entry for q-507e80c4 cites `#219` while the item's own line cites no
+ * PR — so a ref-tie would have marked a genuinely-open part (b) as delivered.
+ */
+function doneRecordsDelivery(entries: DoneEntry[], id: string, text: string): boolean {
+  const norm = (v: string) => v.replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+  const target = norm(summarize(text)).replace(/…$/, "");
+  const sigil = `⟨${id}⟩`;
+  return entries.some((e) => {
+    const t = String(e.text);
+    if (t.includes(sigil)) return true;
+    // A leading recorded-id token is stripped before comparing, so an entry
+    // written as `⟨id⟩ <summary>` and one written as `<summary>` agree.
+    const body = norm(t).replace(/^⟨q-[0-9a-f]{8}⟩\s*/, "");
+    return target.length >= 12 && body.startsWith(target);
+  });
+}
+
 // ---------- next_unblocked ----------
 
 export const nextUnblockedSchema = { project: z.string().min(1), repo: z.string().optional() };
@@ -147,7 +296,34 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   const q = readDoc(repo, QUEUE_DOC);
   if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
   const items = queueItemsOf(q.doc);
-  const open = items.filter((i) => !i.done);
+
+  // ALREADY-DELIVERED ITEMS ARE NEVER RE-OFFERED, and `!i.done` alone does not
+  // establish that.
+  //
+  // MEASURED, 2026-09-01: an item whose work had merged in #196 was still `[ ]`
+  // in the queue — closing it is a separate act from landing it — so it stayed
+  // eligible. A compaction then re-issued its id, it surfaced as the top item,
+  // and it was routed back to the worker that had closed it an hour earlier.
+  // That worker declined because it recognised its own acceptance criteria:
+  // RETAINED CONTEXT, which is not a control and which a `/clear` or a
+  // compaction removes silently.
+  //
+  // So delivery is read from the RECORD instead: an item cited in docs/DONE.md,
+  // or already carrying a 🚧 row on the board, has been handed out. Stable ids
+  // (Task 21.1) are what make this join reliable — with a content-hash id the
+  // board row and the DONE entry stopped matching the moment anyone reworded
+  // the item, which is how the memory was lost in the first place.
+  const delivered = new Set<string>();
+  const doneDoc = readDoc(repo, DONE_DOC);
+  const boardDoc = readDoc(repo, BOARD_DOC);
+  const boardText = boardDoc?.text ?? "";
+  const doneEntries = doneDoc ? doneEntriesOf(doneDoc.doc) : [];
+  const boardRows = boardDoc ? workstreamsV1RowsOf(boardDoc.doc) : [];
+  for (const i of items) {
+    if (boardHoldsItem(boardRows, i.id, String(i.text)) || doneRecordsDelivery(doneEntries, i.id, String(i.text))) delivered.add(i.id);
+  }
+
+  const open = items.filter((i) => !i.done && !delivered.has(i.id));
   const ranked = open
     .map((i, idx) => ({ i, idx }))
     .sort((a, b) => (PRIORITY_ORDER[a.i.priority ?? "P3"] ?? 3) - (PRIORITY_ORDER[b.i.priority ?? "P3"] ?? 3) || a.idx - b.idx);
@@ -161,8 +337,33 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // Skipped VISIBLY, same discipline as a blocked top item — never silently
   // dropped, so a caller can tell "nothing left for me" from "nothing left".
   const notClaimable: { item: string; sweepTag: string }[] = [];
+  // AWAITING A HUMAN (q-e334937d). "Unblocked" means dependency-free, and an
+  // item awaiting a ruling is dependency-free and unbuildable at once. Measured
+  // 2026-09-02: this verb offered q-11257590 as next; the lane read the
+  // acceptance PROSE to learn it awaited David, declined, and picked by hand —
+  // a read every lane offered it would pay again. The fact is now a FIELD on
+  // the item (`**[AWAITS:<who>]**`, read by the seam), never inferred from
+  // prose. Its own axis, checked FIRST: it is the most specific thing that can
+  // be true of an item, and "three items wait on a human" is a fact David can
+  // act on where "nothing to route" is not. Skipped for routing, never dropped.
+  //
+  // GATHERED OVER EVERY OPEN ITEM, NOT OVER `open` — measured on the real queue
+  // the first time this ran: q-11257590 carried the marker and appeared in NO
+  // bucket, because the board holds a "⏸ Parked — awaits David" row naming it
+  // and the delivered-join above reads any board mention as "handed out". The
+  // row written to WARN about the item was what hid it. Routing still honours
+  // the join; this report does not, because its reader is the human the item
+  // waits on, and a pending decision does not stop being pending when someone
+  // writes it on the board.
+  const awaitingDecision: { item: string; id: string; who: string; onBoard: boolean }[] = [];
+  for (const i of items) {
+    if (i.done) continue;
+    const who = awaitingOf(i);
+    if (who) awaitingDecision.push({ item: keyOf(i), id: i.id, who, onBoard: boardText.includes(i.id) });
+  }
   let pick: QueueItem | null = null;
   for (const { i } of ranked) {
+    if (awaitingOf(i)) continue; // reported above; never routed
     const tag = sweepTagOf(i);
     if (tag && /^canon(\.\d+)?$/.test(tag)) {
       notClaimable.push({ item: keyOf(i), sweepTag: tag });
@@ -196,9 +397,15 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     // would read a claimability gap as a dependency, which is a different
     // remedy (route it, don't wait for it).
     notClaimable,
+    // A THIRD AXIS, and not a variant of either above: `skipped` waits on
+    // another ITEM, `notClaimable` is not this caller's to take, and this waits
+    // on a HUMAN. The remedy differs each time (wait · route · ask), so one
+    // list covering them would leave the reader to infer which applies.
+    awaitingDecision,
     boardHunks: [
       ...skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
       ...notClaimable.map((s) => `⏭ skipped — not worker-claimable (${s.sweepTag})`),
+      ...awaitingDecision.map((a) => `⏸ skipped — awaiting decision from ${a.who} (${a.id})`),
     ],
     // A SEPARATE AXIS, deliberately. See noDownstream().
     noDownstream: undiscriminating
@@ -352,9 +559,57 @@ export async function claimTool(args: { project: string; agentId: string; itemId
   // It does not resolve YET, because a freshly cut branch is unpushed. That is
   // correct and `stall_check` says so in those words: an unpushed lane has no
   // shared evidence of activity, which is an absence of evidence rather than a
-  // stall. Enforced at the WRITE as well as the read (board-ref.ts) — a rule the
-  // writer can defeat is a rule the writer defeats.
-  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${boardRefFor(wt.branch ?? "")}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
+  // stall.
+  const intendedRef = boardRefFor(wt.branch ?? "");
+
+  /*
+   * AND NOW ACTUALLY ENFORCED AT THE WRITE.
+   *
+   * The comment here used to claim exactly that — "enforced at the WRITE as well
+   * as the read, a rule the writer can defeat is a rule the writer defeats" —
+   * and it was FALSE. `boardRefFor` PREFIXES `origin/`; it refuses nothing. So
+   * `claim` could still write `origin/main` into a board cell, which
+   * `stall_check` then correctly refuses to measure, leaving a row that can
+   * never stall and never be measured. board-ref.ts's own header states the
+   * rule; #197 shipped the read half and I wrote the sentence and did not do it.
+   *
+   * A rule carrying a false mechanism is worse than an absent rule: the next
+   * reader derives from the mechanism, and this one asserted the very coverage
+   * it lacked.
+   *
+   * REFUSED: the four kinds that are structurally wrong however fresh the lane
+   * is — a shared ref (measures the fleet), a path (not a ref at all), another
+   * agent's branch (measures their work), and an empty cell.
+   *
+   * ALLOWED: `unpushed` and `local-only`, deliberately. A freshly cut branch is
+   * ALWAYS unpushed, so refusing those would refuse every legitimate claim —
+   * the over-narrowing I have now made twice in this classifier's history, where
+   * a rule meant to make a check honest disabled it instead. `merged` is allowed
+   * too but noted, since re-claiming onto a landed branch is unusual rather than
+   * structurally broken.
+   */
+  const refusable = new Set(["shared", "path", "unscoped", "empty"]);
+  const cellVerdict = classifyBoardRef(repo, args.agentId, `\`${intendedRef}\``, `origin/${args.base ?? "main"}`);
+  if (refusable.has(cellVerdict.kind)) {
+    return {
+      ok: false as const,
+      error:
+        `cannot claim: the board cell would name '${intendedRef}', which is not a per-agent activity signal ` +
+        `(${cellVerdict.kind}) — ${"why" in cellVerdict ? cellVerdict.why : ""} ` +
+        `The row would be unmeasurable the moment it was written, so it is refused here rather than reported later.`,
+      item: { id: item.id, priority: item.priority },
+      worktree: { path: wt.path, branch: wt.branch },
+    };
+  }
+
+  // THE ROW NAMES THE ITEM BY ID, so the delivered-join can recognise a row this
+  // verb itself wrote. Measured on the live board: `keyOf` is the item's text
+  // prefix and the recorded `⟨id⟩` token is not part of `text`, so NO
+  // claim-written row has ever carried an id — the join could only ever match
+  // HAND-WRITTEN rows, which is the opposite of what it was for. Stamping it
+  // makes the identification recorded rather than derived from a 60-character
+  // prose prefix that any rewording changes.
+  const boardHunk = `| ⟨${item.id}⟩ ${keyOf(item)} | ${args.agentId} | \`${intendedRef}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
 
   // 2.4b — THE VERB WRITES THE ROW. Reported by default, applied with
   // write:true, matching `land`. A returned hunk that a human pastes is the
@@ -391,6 +646,8 @@ export const landSchema = {
   repo: z.string().optional(),
   base: z.string().optional(),
   write: z.boolean().optional(),
+  /** One-line result, written after the citation on the closed item's line. */
+  result: z.string().optional(),
 };
 
 export async function landTool(args: {
@@ -400,6 +657,7 @@ export async function landTool(args: {
   repo?: string;
   base?: string;
   write?: boolean;
+  result?: string;
 }) {
   const repo = args.repo ?? process.cwd();
   const base = args.base ?? "main";
@@ -459,13 +717,46 @@ export async function landTool(args: {
   const target = args.queueItemId ? items.find((i) => i.id === args.queueItemId) : null;
   if (args.queueItemId && !target) return { ok: false as const, error: `no queue item with id '${args.queueItemId}'` };
 
-  // CLOSE = STATUS ONLY. The item's priority and body BYTES are untouched: the
-  // seam re-renders `- [x] (P2) <text>` from the same text it parsed, so closing
-  // cannot reword an item. That is asserted by a fixture, not by inspection.
+  // CLOSE = STATUS + CITATION. The item's priority and body BYTES are untouched:
+  // the seam re-renders `- [x] (P2) <text>` from the same text it parsed, so
+  // closing cannot reword an item. That is asserted by a fixture, not by
+  // inspection.
+  //
+  // AND THE LINE CITES WHAT CLOSED IT (q-6d21ff84). `doctor:queue-done-loop`
+  // requires a `[x]` item's FIRST LINE to cite the PR that DONE.md records —
+  // that strictness is what makes a closure machine-checkable, and the repo
+  // paid for it. This verb ticked the box and wrote DONE.md and left line 1
+  // uncited, so EVERY successful `land` turned main red at the next root gate
+  // and the coordinator hand-repaired a file the verb had just written
+  // (`c29becd`, and again on q-e334937d). The writer and the auditor were built
+  // to different contracts; the fix belongs in the writer, because loosening
+  // the auditor to accept what the writer emits is how a check stops being one.
+  //
+  // A SUFFIX, NOT A REWRITE. The existing text is preserved byte-for-byte as a
+  // prefix; ` · **closed by <ref>[ — <result>]**` is appended — the exact form
+  // q-40449919 carries after its manual repair. Line 1 only, because line 1 is
+  // all `item.text` is and all the check reads; a citation on a continuation
+  // line satisfies nothing (the occurrence-vs-position trap, hit twice).
+  //
+  // IDEMPOTENT: an item whose line already cites this PR (in any spelling
+  // `refsIn` ties to it) is left byte-identical, so a second `land` cannot
+  // double-cite and a hand-cited item is not re-cited.
   let queueChanged = false;
+  let citationAppended: string | null = null;
+  // The DONE entry and the emitted event describe the WORK, from the text the
+  // item had BEFORE the citation was appended — otherwise the summary would
+  // carry the citation the DONE line already ends with, twice on one line.
+  const originalText = target ? String(target.text) : null;
   if (target) {
     target.done = true;
     queueChanged = true;
+    const prRef = refsIn(args.pr)[0] ?? { raw: args.pr, repo: null, number: n };
+    const contextRepo = originRepoOf(repo);
+    const alreadyCited = refsIn(String(target.text)).some((r) => refsMatch(r, prRef, { contextRepo }));
+    if (!alreadyCited) {
+      citationAppended = ` · **closed by ${args.pr}${args.result ? ` — ${args.result.trim()}` : ""}**`;
+      target.text = `${target.text}${citationAppended}`;
+    }
   }
 
   const already = doneEntriesOf(d.doc).some((e) => new RegExp(`#${n}\\b`).test(String(e.ref ?? "")));
@@ -480,7 +771,7 @@ export async function landTool(args: {
   // So: the summary comes from the item being closed, and a bare `#N` is reported
   // as UNDER-QUALIFIED rather than silently written.
   const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
-  const summary = target ? summarize(target.text) : null;
+  const summary = originalText !== null ? summarize(originalText) : null;
 
   const doneLine =
     already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
@@ -497,8 +788,17 @@ export async function landTool(args: {
   // byte-for-byte: `renderWorkDoc` reproduces every unmodelled line verbatim, and
   // an entry added to the record model renders through the pinned glyph contract.
   const wrote: string[] = [];
+  let stampedNotSupplied: string[] = [];
   if (args.write) {
-    if (queueChanged && writeDoc(repo, QUEUE_DOC, q.doc, q.text)) wrote.push(QUEUE_DOC);
+    if (queueChanged) {
+      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text);
+      if (w.written) wrote.push(QUEUE_DOC);
+      // Rows stamped that this call did not ask to touch. `queueItemId` is the
+      // one item the caller supplied, so anything else here is a row that
+      // arrived unstamped from somewhere: the absorption this verb would
+      // otherwise carry to main under its own name.
+      stampedNotSupplied = w.stamped.filter((id) => id !== args.queueItemId);
+    }
     if (doneLine) {
       const blocks = d.doc.blocks;
       let last = -1;
@@ -516,7 +816,7 @@ export async function landTool(args: {
         return { ok: false as const, error: `the composed DONE line does not parse as done.v1: ${doneLine}` };
       }
       block.entries.push(entry);
-      if (writeDoc(repo, DONE_DOC, d.doc, d.text)) wrote.push(DONE_DOC);
+      if (writeDoc(repo, DONE_DOC, d.doc, d.text).written) wrote.push(DONE_DOC);
     }
   }
 
@@ -535,7 +835,7 @@ export async function landTool(args: {
   if (args.write && target) {
     const after = readDoc(repo, DONE_DOC);
     const recordText = after?.text ?? "";
-    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(target.text) };
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(originalText ?? "") };
     const derived = eventIsDerived(recordText, ev);
     if (!derived.ok) {
       events.refused.push(derived.error);
@@ -553,7 +853,31 @@ export async function landTool(args: {
     pr: `#${n}`,
     comparedAgainst: ref,
     landedIn: landedIn.slice(0, 8),
-    queueItem: target ? { id: target.id, closed: true, textUnchanged: true } : null,
+    // THE ABSORBING WRITER LEARNS IT ABSORBED SOMETHING. The aide's
+    // diff-before-rename guard REFUSES on a foreign change; this REPORTS one it
+    // fixed, so a foreign row cannot pass silently in either direction.
+    ...(stampedNotSupplied.length
+      ? {
+          stampedNotSupplied,
+          stampNote:
+            `recorded an id for ${stampedNotSupplied.length} queue item(s) this call did not supply (${stampedNotSupplied.join(", ")}) — ` +
+            `they arrived unstamped, most likely a raw text append, and would have reddened doctor:queue-id-recorded on whoever committed next. ` +
+            `Each id written is the one the item already had, so no value changed.`,
+        }
+      : {}),
+    queueItem: target
+      ? {
+          id: target.id,
+          closed: true,
+          // `textUnchanged` keeps its meaning — the priority and the body bytes
+          // the item had are all still there, in place. What is new is a SUFFIX
+          // on line 1, reported separately so a reader can tell "reworded" from
+          // "cited": null when the line already cited this PR.
+          textUnchanged: citationAppended === null,
+          bodyPreserved: true,
+          citationAppended,
+        }
+      : null,
     events,
     candidates: target
       ? undefined
@@ -757,15 +1081,47 @@ export async function mergeTool(
   // copied, because a copied grammar is two grammars the moment one is fixed.
   const ticked = newlyTickedInDiff(f.diff ?? "");
   if (ticked.size) {
-    const cited = phaseCitationsIn(f.citationText ?? "");
-    const uncited = [...ticked].filter((k) => !cited.has(k));
+    /*
+     * A RELATIONAL CITATION DOES NOT EVIDENCE A TICK.
+     *
+     * "unblocks Phase 5.2 Task 15.6" names the task without claiming it is done,
+     * so a PR that ticks 15.6's box and cites it that way is exactly as
+     * unevidenced as one that never mentioned it. Measured on the other side of
+     * this grammar the same day: doctor read that sentence in DONE.md as a
+     * completion claim and red-gated main.
+     *
+     * The two cases are REPORTED SEPARATELY, because they need different fixes
+     * and "UNCITED" would send someone looking for a citation that is already
+     * there. A relational citation needs REWORDING; an absent one needs ADDING.
+     */
+    const detail = phaseCitationsDetailed(f.citationText ?? "");
+    const closes = new Set(detail.filter((c) => c.relation === "claim").map((c) => c.key));
+    const relational = new Map(detail.filter((c) => c.relation === "reference").map((c) => [c.key, c.marker]));
+    const uncited = [...ticked].filter((k) => !closes.has(k));
     if (uncited.length) {
-      const names = uncited.map((k) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; });
+      const nameOf = (k: string) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; };
+      const names = uncited.map(nameOf);
+      const worded = uncited.filter((k) => relational.has(k));
+      const missing = uncited.filter((k) => !relational.has(k));
+      const parts: string[] = [];
+      if (missing.length) {
+        parts.push(
+          `${missing.length} NOT CITED AT ALL: ${missing.map(nameOf).join(", ")} — name them in the PR title or a commit ` +
+            `subject (e.g. "${nameOf(missing[0] as string)}"), the subject being what survives a squash merge`,
+        );
+      }
+      if (worded.length) {
+        parts.push(
+          `${worded.length} cited only RELATIONALLY: ` +
+            worded.map((k) => `${nameOf(k)} (after '${relational.get(k)}')`).join(", ") +
+            ` — that names the task without claiming it is done, so it evidences nothing. Reword it, or drop the tick`,
+        );
+      }
       return {
         ok: false as const,
         error:
-          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNCITED: ${names.join(", ")}. ` +
-          `Once this merges, the tick claims progress that nothing in history evidences. Name them in the PR title or a commit subject (e.g. "${names[0]}") — the subject is what survives a squash merge.`,
+          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNEVIDENCED. ` +
+          `${parts.join(". ")}. Once this merges, the tick claims progress nothing in history supports.`,
         verdict,
         uncited: names,
       };

package/src/tools/registry.ts

@@ -79,8 +79,11 @@ export const registerSchema = {
   project: z.string().optional(),
   role: roleInputSchema.optional(),
   // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-  // that is LIVE on the bus refuses unless the call presents that agent's
-  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  // that is PROVABLY LIVE on the bus refuses unless the call presents that
+  // agent's token (tokens.json / coord-token) — `force` alone no longer
+  // overrides a provably live incumbent (q-314e0187). `force` still bypasses
+  // the guard when liveness cannot be verified, or the id is verified absent.
+  // Both ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
   // PROSE-ONLY EXEMPTION (Phase 5.1 Task 12.8). `true` grants it, `false`

package/src/tools/rooms.ts

@@ -60,6 +60,7 @@ import {
   setOffset,
   sysMsg,
   moveFile,
+  agentIdFromCursorFilename,
   STALE_MS,
   EVICT_MS,
   MAX_WAIT_MS,
@@ -284,7 +285,7 @@ export async function deleteRoomTool(args: { agentId: string; room: string; forc
   // a now-deleted file.
   const cursorsAdjusted: string[] = [];
   for (const fname of await listCursorFiles()) {
-    const id = fname.replace(/\.json$/, "");
+    const { id } = agentIdFromCursorFilename(fname);
     const cursorPath = path.join(CURSOR_DIR, fname);
     let touched = false;
     await updateJson<Cursor>(cursorPath, {}, (current) => {