agent-coord-mcp 0.26.21 → 0.26.23

package/src/tools/records.ts

@@ -12,7 +12,7 @@
  * that drifts.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 
@@ -30,17 +30,22 @@ import {
   sweepTagOf,
   awaitingOf,
   refsIn,
+  closingCitation,
   refsMatch,
   workstreamsV1RowsOf,
+  workStateOf,
+  declarationOf,
+  type WorkState,
   type WorkstreamsV1Row,
   type DoneEntry,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
 import { ROOT } from "../store.js";
-import { verdictsFor, gatedAt } from "../gated-head.js";
+import { verdictsFor, gatedBy, prVerdictsIn } from "../gated-head.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
-import { haltState, isInFlightStatus } from "./stall.js";
+import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
+import { prRefsIn } from "./record-events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
 const DONE_DOC = "docs/DONE.md";
@@ -160,10 +165,58 @@ const git = (repo: string, args: string[]): string =>
   execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
 
 /** `#123` / `owner/repo#123` → "123". */
+
 function prNumber(pr: string): string | null {
   const m = /#(\d+)\b/.exec(String(pr)) ?? /^(\d+)$/.exec(String(pr).trim());
   return m ? (m[1] as string) : null;
 }
+/** ⟨q-cbace757⟩ — EVERY PR number a citation names, in order; a multi-PR closer is N citations. */
+function prNumbersOf(pr: string): string[] {
+  const out: string[] = [];
+  for (const m of String(pr).matchAll(/#(\d+)\b/g)) if (!out.includes(m[1]!)) out.push(m[1]!);
+  if (!out.length) { const one = prNumber(pr); if (one) out.push(one); }
+  return out;
+}
+/*
+ * ⟨q-b7198479⟩ — THE LOOKUP IS NOT BOUNDED BY A WINDOW. `git log -n 400` missed
+ * #245's squash 777 commits back on an 1806-commit main and the verb then
+ * asserted "#245 is not on origin/main" as a fact — a truncated search reported
+ * as an absence, at the verb that writes the delivery record, and worded with a
+ * mechanism (target tip vs merge base) that had nothing to do with it. At the
+ * fleet's speed (~200 record commits a day) 400 is about two days, so it fires
+ * precisely on the oldest rows, the ones closed late.
+ *
+ * Now: `git log --grep` over the WHOLE of the ref, then the SUBJECT is judged
+ * BY IDENTITY, the rule #327's mergeOf and the closing-line grammar already use:
+ * the landing is the commit whose subject ENDS with the forge's `(#N)` marker.
+ * A bare `#N` anywhere is a mention, never a landing — qa measured the first
+ * cut of this (`\(#N\)|#N\b`, newest first) on live origin/main: 149 of 322
+ * squash-merged PRs resolved to their CLOSURE or board commit ("docs(record):
+ * close … by content on #245"), which carry the bare number in the subject and
+ * sit newer than the squash. Among trailing-(#N) subjects the OLDEST wins: a
+ * hand-written "docs: log Task 10 (#164)" copied the marker 36 s after #164's
+ * squash and would otherwise be taken for it. The one PR of 323 on this main
+ * that landed as a merge commit (#108, "Merge pull request #108 from …") is the
+ * second identity form — the forge's own, not a mention — and is the last
+ * resort, consulted only when no trailing form exists. A miss reports what was
+ * searched — every subject on the ref — never a mechanism it did not test.
+ */
+export function landingCommitOf(repo: string, ref: string, n: string): { sha: string | null; searched: number } {
+  const searched = Number(git(repo, ["rev-list", "--count", ref])) || 0;
+  // git's --grep is a basic regex with no `\b`; identity is decided on the SUBJECT below.
+  const out = git(repo, ["log", ref, "--format=%H%x00%s", `--grep=#${n}`]);
+  const trailing = new RegExp(`\\(#${n}\\)\\s*$`);
+  const mergeForm = new RegExp(`^Merge pull request #${n}(?:\\s|$)`);
+  let landing: string | null = null;
+  let merge: string | null = null;
+  for (const line of out.split("\n")) {
+    const [sha, subject = ""] = line.split("\x00");
+    if (!sha) continue;
+    if (trailing.test(subject)) landing = sha; // newest first: the last hit is the OLDEST
+    else if (!merge && mergeForm.test(subject)) merge = sha;
+  }
+  return { sha: landing ?? merge, searched };
+}
 
 /**
  * The `owner/repo` a BARE `#N` in this repo's docs should be read as naming —
@@ -287,18 +340,71 @@ function rowSubjectIds(row: WorkstreamsV1Row): string[] {
   return [...String(row.stream).matchAll(/\b(q-[0-9a-f]{8})\b/g)].map((m) => m[1] as string);
 }
 
+/** What a board row says about an item it names as its SUBJECT. */
+export type BoardHold = {
+  /** The state the seam read off the row's Status cell. */
+  state: WorkState;
+  /** The routing reason: the state, except `parked` is split into held · queued · parked. */
+  why: string;
+  /** The declaration the reason was read from — never the commentary after it. */
+  status: string;
+  /** Whether the row's Branch · Worktree cell names anything at all. */
+  builtWork: boolean;
+  branch: string;
+};
+
+/*
+ * ⭐ THE NUANCE THE SEAM DOES NOT SETTLE, SETTLED HERE (⟨q-a42503cb⟩): `⏸
+ * MERGE-HELD` and `⏸ Parked — awaits David` are BOTH `parked` to
+ * `workStateOf` and both `open` to `coarseOf`, yet one has BUILT WORK gated
+ * green in an open PR and the other has nothing behind it. Reporting them under
+ * one word re-creates the defect with a wider net: a reader told "parked" for
+ * `#292`'s row would go and build it.
+ *
+ * Two INDEPENDENT facts, deliberately not one: the WORD comes from the
+ * declaration (`held` · `queued` · `parked`), and `builtWork` comes from the
+ * Branch · Worktree cell. A row can say MERGE-HELD with an empty branch cell,
+ * and that disagreement is worth seeing rather than resolving.
+ */
+const STATUS_DECORATION = /^[\s*⭐]+/u;
+function holdReasonOf(state: WorkState, status: string): string {
+  if (state !== "parked") return state;
+  const decl = declarationOf(String(status).replace(STATUS_DECORATION, ""));
+  if (/\bheld\b/i.test(decl)) return "held";
+  if (/\bqueued\b/i.test(decl)) return "queued";
+  return "parked";
+}
+
 /**
- * Does the board show this item as IN SOMEBODY'S HANDS?
+ * What does the board say about this item, if it is the SUBJECT of any row?
+ *
+ * ⛔⛆ ANY ROW WHOSE SUBJECT IS THE ITEM EXCLUDES IT FROM ROUTING, AND SAYS WHY
+ * (⟨q-a42503cb⟩). This was a boolean gated on `isInFlightStatus` — 🚧 and 🔍
+ * only — so a `⏸ MERGE-HELD` row with its work gated green in `#292` left
+ * its item at the TOP of the pool: a seat taking it would have rebuilt the PR.
+ * Measured on the live board 2026-09-14: seven `⏸` rows, every one the
+ * coordinator's most careful bookkeeping, every one invisible to this join.
  *
- * 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.
+ * ⚠ THIS SUPERSEDES HALF OF ⟨q-2ba7f0c5⟩'S RULING, AND KEEPS ITS REASON. That
+ * fix made a `⏸ Parked` row NOT silence its item, because the alternative
+ * then was a SILENT drop with no axis. The drop is no longer silent: the item
+ * lands on `delivered` with the row's state as its `why`, and an `AWAITS`
+ * item still reaches `awaitingDecision`, which is gathered over every open
+ * item before this join. What ⟨q-2ba7f0c5⟩ actually defended — a warning row
+ * must not make its item VANISH — still holds; what changes is that a warning
+ * row now also stops the item being HANDED OUT, which is what a warning is for.
+ *
+ * Conditions:
  *   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.
+ *   STATE   whatever the seam reads: in-progress, in-review, parked (split
+ *           into held · queued · parked, see `holdReasonOf`), blocked,
+ *           orphaned, done, … An UNRECOGNISED glyph is `unknown` and STILL
+ *           excludes: the row is on the board with this item as its subject,
+ *           and offering it anyway is the silent path this exists to close.
+ *           A `✅ Done` row excludes too — that item is offerable to nobody.
  *
  * 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
@@ -309,14 +415,24 @@ function rowSubjectIds(row: WorkstreamsV1Row): string[] {
  * 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 {
+function boardHoldOf(rows: WorkstreamsV1Row[], id: string, text: string): BoardHold | null {
   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;
+  for (const r of rows) {
     const stream = String(r.stream).replace(/\s+/g, " ").trim();
-    return key.length >= 20 && stream.startsWith(key.slice(0, Math.min(key.length, 60)));
-  });
+    const subject =
+      rowSubjectIds(r).includes(id) || (key.length >= 20 && stream.startsWith(key.slice(0, Math.min(key.length, 60))));
+    if (!subject) continue;
+    const state = workStateOf(r.status);
+    const branch = String(r.branchWorktree).replace(/[`*]/g, "").trim();
+    return {
+      state,
+      why: holdReasonOf(state, r.status),
+      status: declarationOf(String(r.status).replace(STATUS_DECORATION, "")),
+      builtWork: branch.length > 0 && branch !== "—" && branch !== "-",
+      branch,
+    };
+  }
+  return null;
 }
 
 /**
@@ -345,7 +461,7 @@ function boardHoldsItem(rows: WorkstreamsV1Row[], id: string, text: string): boo
  * false positives, because open rows cite refs as EVIDENCE.
  *
  * ✅ WHAT SURVIVES IS THE COMPOSED-SUMMARY ARM, and it is a DIFFERENT EVIDENCE
- * CLASS — the same distinction that keeps `boardHoldsItem`. It does not infer
+ * CLASS — the same distinction that keeps `boardHoldOf`. It does not infer
  * delivery from prose: it requires the entry to carry the item's own
  * deterministically composed text, `summarize(item.text)`, which a VERB writes.
  * A citation cannot accidentally satisfy it.
@@ -434,7 +550,7 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   //
   // ⚠ THE REASON IS NOW CARRIED, so exclusion and explanation cannot drift apart:
   // a row is excluded BY a named cause, and the cause is what gets reported.
-  const deliveredBy = new Map<string, "board" | "done">();
+  const deliveredBy = new Map<string, { reason: "board"; hold: BoardHold } | { reason: "done" }>();
   const doneDoc = readDoc(repo, DONE_DOC);
   const boardDoc = readDoc(repo, BOARD_DOC);
   const boardText = boardDoc?.text ?? "";
@@ -443,10 +559,12 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   for (const i of items) {
     if (i.done) continue; // already off `open` by the checkbox; not an exclusion this axis owns
     // Board first, and the order is load-bearing for the REPORT rather than the
-    // routing: both causes exclude, but a live 🚧 row is a different remedy
-    // (wait, or ask its owner) from a landed delivery (close the row).
-    if (boardHoldsItem(boardRows, i.id, String(i.text))) deliveredBy.set(i.id, "board");
-    else if (doneRecordsDelivery(doneEntries, i.id, String(i.text))) deliveredBy.set(i.id, "done");
+    // routing: both causes exclude, but a board row is a different remedy
+    // (wait for the merge · ask its owner · ask the human it awaits, by its
+    // `why`) from a landed delivery (close the row).
+    const hold = boardHoldOf(boardRows, i.id, String(i.text));
+    if (hold) deliveredBy.set(i.id, { reason: "board", hold });
+    else if (doneRecordsDelivery(doneEntries, i.id, String(i.text))) deliveredBy.set(i.id, { reason: "done" });
   }
 
   const open = items.filter((i) => !i.done && !deliveredBy.has(i.id));
@@ -454,9 +572,21 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // THE AXIS THE SUBTRACTION USED TO SKIP. Every row absent from `open` for this
   // reason is named here, INCLUDING correctly-delivered ones: a correct exclusion
   // reported silently is the same defect as an incorrect one.
+  //
+  // ⛔ THE REASON NAMES THE STATE, NOT JUST THE DOCUMENT (⟨q-a42503cb⟩). "on
+  // the board" covered a live 🚧 lane and a `⏸ MERGE-HELD` PR with one word,
+  // and the two want opposite things from the reader — leave the first alone,
+  // MERGE the second. `why` is the seam's state (parked split into held ·
+  // queued · parked) and `builtWork` says whether the row names a branch at
+  // all, so "held with nothing behind it" is visible rather than resolved.
   const delivered = items
     .filter((i) => !i.done && deliveredBy.has(i.id))
-    .map((i) => ({ item: keyOf(i), id: i.id, reason: deliveredBy.get(i.id)! }));
+    .map((i) => {
+      const d = deliveredBy.get(i.id)!;
+      return d.reason === "board"
+        ? { item: keyOf(i), id: i.id, reason: "board" as const, why: d.hold.why, state: d.hold.state, status: d.hold.status, builtWork: d.hold.builtWork, branch: d.hold.branch }
+        : { item: keyOf(i), id: i.id, reason: "done" as const, why: "recorded in DONE.md" };
+    });
 
   // ⛔⛆ A DUPLICATED ID IS A SILENT DOUBLE-EXCLUSION, AND IT IS THIS ROW'S OWN
   // DEFECT ONE LEVEL DOWN. Queue ids are STABLE, derived from the row's text, so
@@ -590,7 +720,7 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
       ...duplicateIds.map((d) => `⚠ ${d.rows} open rows share the id ${d.id} — one record excludes all of them`),
       ...delivered.map((d) =>
         d.reason === "board"
-          ? `⏭ not offered — already on the board (${d.id})`
+          ? `⏭ not offered — on the board as ${d.why}${d.builtWork ? ` with built work on ${d.branch}` : " with no branch on the row"} (${d.id})`
           : `⏭ not offered — delivery recorded in DONE.md (${d.id})`,
       ),
     ],
@@ -662,9 +792,16 @@ export const claimSchema = {
   base: z.string().optional(),
   task: z.string().optional(),
   write: z.boolean().optional(),
+  /**
+   * ⟨q-5d1c8e04⟩ — A SLICE WITH NO CODE DELIVERABLE, said as a first-class value.
+   * What the slice delivers instead (a ruling, a canon edit, a measurement).
+   * No worktree is cut; the board cell carries the statement in words, which
+   * the grammar and `stall_check` both read as DELIBERATE rather than missing.
+   */
+  noCodeDeliverable: z.string().min(1).optional(),
 };
 
-export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string; write?: boolean }) {
+export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string; write?: boolean; noCodeDeliverable?: string }) {
   const halt = haltState();
   if (halt.halted) {
     return {
@@ -698,6 +835,24 @@ export async function claimTool(args: { project: string; agentId: string; itemId
   // A worktree that cannot be ensured is a REFUSAL, not a warning. Binding an
   // item to an agent with nowhere isolated to work is the shared-checkout failure
   // this pair exists to prevent.
+  // ⟨q-5d1c8e04⟩ — NO CODE DELIVERABLE: no tree, and the cell SAYS so. Five
+  // seats wrote this by hand in five spellings because the verb had no way to
+  // say it; `stall_check` reads the prose cell as deliberately branchless and
+  // keeps the row out of its population rather than calling it unmeasurable.
+  if (args.noCodeDeliverable) {
+    const cell = `no code deliverable · ${args.noCodeDeliverable.replace(/[|\n]/g, " ").trim()}`;
+    const boardHunk = `| ⟨${item.id}⟩ ${keyOf(item)} | ${args.agentId} | ${cell} | 🚧 In Progress | — | claimed |`;
+    let board: { action: string; path?: string } = { action: "reported" };
+    const b = readDoc(repo, BOARD_DOC);
+    if (!b) board = { action: `no ${BOARD_DOC} under '${repo}' — row NOT written` };
+    else if (args.write) {
+      const next = upsertBoardRow(b.text, args.agentId, boardHunk);
+      if (next.action !== "unchanged") writeFileSync(path.join(repo, BOARD_DOC), next.text);
+      board = { action: next.action, path: BOARD_DOC };
+    }
+    return { ok: true as const, project: args.project, agentId: args.agentId, item: { id: item.id, priority: item.priority, text: item.text }, boardHunk, board, worktreeEnsured: false, noCodeDeliverable: args.noCodeDeliverable };
+  }
+
   const wt = await ensureWorktreeTool({
     agentId: args.agentId,
     repo,
@@ -841,23 +996,41 @@ export const landSchema = {
  * What the recording step needs to know about a merge: which head actually
  * landed, and when. Injected so the report is provable without the network.
  */
-export type MergeFacts = { headRefOid: string; mergedAt: string } | null;
+export type PrComment = { body: string; createdAt?: string; author?: string };
+/** ⟨q-5a93c2d7⟩ — the PR page is a verdict channel too, so its comments travel with the merge facts. */
+export type MergeFacts = { headRefOid: string; mergedAt: string; comments?: PrComment[] } | null;
 export type ReadMergeFacts = (repo: string, n: string) => MergeFacts;
 const ghMergeFacts: ReadMergeFacts = (repo, n) => {
   try {
-    const out = execFileSync("gh", ["pr", "view", n, "--json", "headRefOid,mergedAt"], {
+    const out = execFileSync("gh", ["pr", "view", n, "--json", "headRefOid,mergedAt,comments"], {
       cwd: repo,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
     });
-    const j = JSON.parse(out) as { headRefOid?: string; mergedAt?: string };
+    const j = JSON.parse(out) as { headRefOid?: string; mergedAt?: string; comments?: { body?: string; createdAt?: string; author?: { login?: string } }[] };
     if (!j.headRefOid || !j.mergedAt) return null;
-    return { headRefOid: String(j.headRefOid), mergedAt: String(j.mergedAt) };
+    return {
+      headRefOid: String(j.headRefOid),
+      mergedAt: String(j.mergedAt),
+      comments: (j.comments ?? []).map((c) => ({ body: String(c.body ?? ""), createdAt: c.createdAt, author: c.author?.login })),
+    };
   } catch {
     return null;
   }
 };
 
+/** ⟨q-6b3af019⟩ — the row ids the landing commit of #n cites, read off its SUBJECT on the base (the `(#n)` squash marker). */
+export function landingCitations(repo: string, n: string): string[] {
+  let subjects = "";
+  for (const base of ["origin/main", "main"]) {
+    try { subjects = git(repo, ["log", base, "--format=%s", "--fixed-strings", `--grep=(#${n})`, "-n", "20"]); break; } catch { /* next */ }
+  }
+  const marker = `(#${n})`;
+  const landing = subjects.split("\n").find((s) => s.trimEnd().endsWith(marker));
+  return landing ? [...new Set(landing.match(/q-[0-9a-f]{8}/g) ?? [])] : [];
+}
+
 export async function landTool(
   args: {
   project: string;
@@ -890,19 +1063,31 @@ export async function landTool(
   const ref = `origin/${base}`;
   let landedIn: string | null = null;
   let reason: string | null = null;
+  // ⟨q-cbace757⟩ — every cited PR must be on the ref, not only the first.
+  const numbers = prNumbersOf(args.pr);
+  const landings: Record<string, string> = {};
+  let searched = 0;
+  const missing: string[] = [];
   try {
-    const subjects = git(repo, ["log", "-n", "400", "--format=%H %s", ref]);
-    const hit = subjects.split("\n").find((l) => new RegExp(`\\(#${n}\\)|#${n}\\b`).test(l));
-    landedIn = hit ? (hit.split(" ")[0] as string) : null;
+    for (const num of numbers) {
+      const found = landingCommitOf(repo, ref, num);
+      searched = found.searched;
+      if (found.sha) landings[num] = found.sha; else missing.push(num);
+    }
+    landedIn = landings[n] ?? null;
   } catch (e) {
     reason = `could not read ${ref} (${String((e as Error).message).split("\n")[0]}) — NOT checked, which is not the same as checked and absent`;
   }
   if (reason) return { ok: false as const, error: reason };
-  if (!landedIn) {
+  if (!landedIn || missing.length) {
     return {
       ok: false as const,
-      error: `#${n} is not on ${ref} — refusing to record it as landed. Compared against the TARGET TIP (${ref}), not a merge base: an item merged after this branch was cut is missing from the base too.`,
+      error:
+        `${missing.map((m) => `#${m}`).join(", ")} not found on ${ref}: none of the ${searched} commit subject(s) on ${ref} carries ` +
+        `${missing.map((m) => `"(#${m})"`).join(" or ")} — refusing to record it as landed. The whole of ${ref} was searched, not a window; ` +
+        `a PR merged under another number or never merged reads the same here — check \`gh pr view\`.`,
       comparedAgainst: ref,
+      searched,
     };
   }
 
@@ -926,6 +1111,17 @@ export async function landTool(
   // `queueItemId` it closes nothing and reports the candidates for the caller to
   // pick, saying so.
   const candidates = items.filter((i) => !i.done && new RegExp(`#${n}\\b`).test(String(i.text)));
+  // ⟨q-6b3af019⟩ — SIBLINGS: open rows that NAME an id this PR cites. q-b4e7c209
+  // shipped under #250/#251 (both citing q-0b8e5c47) and q-0c5e73a1 under #261
+  // (cited as "slice A" of q-6ce4a8d0): the delivered row named the cited one.
+  // The ids are read off the LANDING COMMIT'S SUBJECT on the base — the record
+  // every check reads, local, no network — and listed beside the #N candidates
+  // at the one moment both facts are in hand. Closing nothing: a sibling is a
+  // question for the coordinator, not a claim.
+  const citedIds = landingCitations(repo, n);
+  const siblings = items
+    .filter((i) => !i.done && !citedIds.includes(i.id) && i.id !== args.queueItemId && citedIds.some((c) => String(i.text).includes(c)))
+    .map((i) => ({ id: i.id, priority: i.priority, names: citedIds.filter((c) => String(i.text).includes(c)) }));
   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}'` };
 
@@ -964,7 +1160,35 @@ export async function landTool(
     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 }));
+    /*
+     * ⛔⛆ "ALREADY CITED" IS A QUESTION ABOUT THE CLOSING POSITION, NOT THE ROW (⟨q-217cc151⟩).
+     *
+     * This asked whether the PR number appears ANYWHERE in the row, so a row that
+     * DISCUSSES its own closer read as already cited and `land` wrote no token.
+     * The natural experiment that isolates it — three rows, one variable:
+     *
+     *   ⟨q-8a7b04f2⟩  mentions #269 ×4, its closer #271 ZERO times  ->  TOKEN WRITTEN
+     *   ⟨q-5f27b1ae⟩  mentions its own closer #269 ×1               ->  NO TOKEN
+     *   ⟨q-8db146d0⟩  mentions its own closer #272 ×2               ->  NO TOKEN
+     *
+     * ⭐ THE VARIABLE IS SELF-REFERENCE, NOT REF DENSITY. A row naming four of
+     * somebody else's PRs is cited normally; a row naming its own once is not. So the
+     * better a row documents what closed it, the more certainly the closure goes
+     * unwritten — and the ARTEFACT is what loses, silently.
+     *
+     * ⚠ RETIRED ONCE AS ⟨q-2b91c188⟩, AND THAT RETIREMENT WAS CORRECT FOR THE QUESTION
+     * ASKED: the behaviour is harmless to every CONSUMER, because both readers accept
+     * a line-1 prose mention and `doctor` falls back to the row. That was measured and
+     * a patch was reverted rather than shipped. What nobody asked was what it does to
+     * the ARTEFACT — a closure whose citation sits in no fixed place. Position is what
+     * makes a ref a citation, and that rule applies to the verb that WRITES one.
+     *
+     * ⛔ THE READER IS NOT TOUCHED HERE. Fixing the writer forward does nothing for
+     * rows already written, and narrowing the reader is what ⟨q-bf162723⟩ established
+     * must never happen.
+     */
+    const closingHere: ReturnType<typeof refsIn> = closingCitation(String(target.text))?.refs ?? [];
+    const alreadyCited = closingHere.some((r) => refsMatch(r, prRef, { contextRepo }));
     if (!alreadyCited) {
       citationAppended = ` · **closed by ${args.pr}${args.result ? ` — ${args.result.trim()}` : ""}**`;
       target.text = `${target.text}${citationAppended}`;
@@ -1095,7 +1319,9 @@ export async function landTool(
   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(originalText ?? "") };
+    // ⟨q-cbace757⟩ — one event, every cited ref; each checked against the record on its own.
+    const refs = prRefsIn(args.pr);
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: refs.length ? refs.join(", ") : args.pr, summary: summarize(originalText ?? ""), ...(refs.length > 1 ? { refs } : {}) };
     const derived = eventIsDerived(recordText, ev);
     if (!derived.ok) {
       events.refused.push(derived.error);
@@ -1129,10 +1355,32 @@ export async function landTool(
     if (log === null) return { checked: false as const, note: `could not read the verdict log for '${args.project}' — whether #${n}'s merged head was gated is UNKNOWN, not clean.` };
     const at = Date.parse(mf.mergedAt);
     if (!Number.isFinite(at)) return { checked: false as const, note: `#${n} reports an unparseable mergedAt ('${mf.mergedAt}') — cannot place the merge in time.` };
-    const { verdicts, unparsed } = verdictsFor(log, n);
-    const a = gatedAt(verdicts, mf.headRefOid, at);
+    const { verdicts: bus, unparsed } = verdictsFor(log, n);
+    // ⟨q-5a93c2d7⟩ — both channels, one predicate: the bus's typed records and
+    // the PR page's typed lines. Gatedness is (head sha, typed verdict); the
+    // merge time only DISCLOSES lateness, in words, beside the answer.
+    const verdicts = [...bus.map((v) => ({ ...v, channel: "bus" as const })), ...prVerdictsIn(mf.comments ?? [])];
+    const a = gatedBy(verdicts, mf.headRefOid, at);
     if (a.gated) {
-      return { checked: true as const, gated: true as const, head: mf.headRefOid.slice(0, 8), by: { from: a.by.from, sha: a.by.head.slice(0, 8) } };
+      const late = (a.lateByMs ?? 0) > 0;
+      return {
+        checked: true as const,
+        gated: true as const,
+        head: mf.headRefOid.slice(0, 8),
+        // ⟨q-dcbaf544⟩ — `from` here is the GATER (`gatedBy ?? from`), never the
+        // sender alone; `attribution` says whether that is a seat or the account.
+        by: {
+          from: a.gater,
+          sha: a.by.head.slice(0, 8),
+          channel: a.by.channel ?? "bus",
+          attribution: a.attribution,
+          ...(a.by.scribe ?? a.seatRecord?.scribe ? { scribe: a.seatRecord?.scribe ?? a.by.scribe } : {}),
+          ...(a.seatRecord ? { firstSeenOnPr: new Date(a.by.ts).toISOString(), seatRecordedAt: new Date(a.seatRecord.ts).toISOString() } : {}),
+        },
+        recordedAfterMerge: late,
+        verified: a.verified,
+        ...(late ? { note: `GATED, LATE RECORD: #${n} — ${a.verified}.` } : {}),
+      };
     }
     return {
       checked: true as const,
@@ -1142,7 +1390,7 @@ export async function landTool(
       gatedInstead: (a.crossed ?? []).map((c) => c.gatedSha.slice(0, 8)),
       note:
         `UNGATED MERGE RECORDED: #${n} merged ${mf.headRefOid.slice(0, 8)} and ${a.reason}. ` +
-        `The record is written — this is a report, not a refusal — but the merge was not covered by a verdict when it happened.` +
+        `The record is written — this is a report, not a refusal — but no typed verdict bound to the merged head exists in any channel.` +
         (unparsed ? ` (${unparsed} log line(s) unreadable and skipped.)` : ""),
     };
   })();
@@ -1183,6 +1431,11 @@ export async function landTool(
     candidates: target
       ? undefined
       : candidates.map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),
+    // ⟨q-6b3af019⟩ — open rows naming an id this PR's landing commit cites; none closed.
+    siblings,
+    ...(siblings.length
+      ? { note_siblings: `${siblings.length} open row(s) NAME an id #${n} cites (${citedIds.join(", ")}) and are not cited themselves — work shipped under another row's citation is how q-b4e7c209 and q-0c5e73a1 sat open; judge each, close none from here.` }
+      : {}),
     ...(target || !candidates.length
       ? {}
       : {
@@ -1271,6 +1524,8 @@ export type PrFacts = {
   diff?: string;
   /** Everything that will survive the merge as a citation: title + commit subjects + body. */
   citationText?: string;
+  /** ⟨q-5a93c2d7⟩ — the PR page's comments, a verdict channel. */
+  comments?: PrComment[];
 };
 const ghFacts = (repo: string, n: string): PrFacts => {
   const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup,headRefOid"], {
@@ -1290,7 +1545,7 @@ const ghFacts = (repo: string, n: string): PrFacts => {
   // history: the PR title (which becomes the squash subject) and the commit
   // subjects. The body is included because a reviewer reads it, but a claim
   // that lives only in a comment thread is not a record.
-  const meta = JSON.parse(gh(["pr", "view", n, "--json", "title,body,commits"]) || "{}") as Record<string, unknown>;
+  const meta = JSON.parse(gh(["pr", "view", n, "--json", "title,body,commits,comments"]) || "{}") as Record<string, unknown>;
   const subjects = ((meta.commits as { messageHeadline?: string }[] | undefined) ?? [])
     .map((c) => c.messageHeadline ?? "")
     .join("\n");
@@ -1298,6 +1553,7 @@ const ghFacts = (repo: string, n: string): PrFacts => {
     state: String(j.state ?? ""),
     mergeable: String(j.mergeable ?? ""),
     headRefOid: String(j.headRefOid ?? ""),
+    comments: ((meta.comments as { body?: string; createdAt?: string; author?: { login?: string } }[] | undefined) ?? []).map((c) => ({ body: String(c.body ?? ""), createdAt: c.createdAt, author: c.author?.login })),
     checks: (j.statusCheckRollup as unknown[]) ?? [],
     diff: gh(["pr", "diff", n]),
     citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
@@ -1332,9 +1588,24 @@ const ghMerge: DoMerge = (repo, n, method) => {
  * only one of them is safe to merge on.
  */
 export type ReadVerdictLog = (project: string) => string | null;
+/**
+ * ⟨q-5a93c2d7⟩ — EVERY room, not the project's alone: "any channel" means a
+ * verdict recorded in another room still counts for this head. The project
+ * room is read first so a missing bus is still a null (unknown), never an
+ * empty string (nothing).
+ */
 const roomLog: ReadVerdictLog = (project) => {
   try {
-    return readFileSync(path.join(ROOT, "rooms", `${project}.jsonl`), "utf8");
+    const own = readFileSync(path.join(ROOT, "rooms", `${project}.jsonl`), "utf8");
+    let others = "";
+    try {
+      const dir = path.join(ROOT, "rooms");
+      others = readdirSync(dir)
+        .filter((f) => f.endsWith(".jsonl") && f !== `${project}.jsonl`)
+        .map((f) => readFileSync(path.join(dir, f), "utf8"))
+        .join("\n");
+    } catch { /* other rooms are optional */ }
+    return others ? `${own}\n${others}` : own;
   } catch {
     return null;
   }
@@ -1484,8 +1755,9 @@ export async function mergeTool(
       verdict,
     };
   }
-  const { verdicts, unparsed } = verdictsFor(log, n);
-  const gate = gatedAt(verdicts, head, Date.now());
+  const { verdicts: busVerdicts, unparsed } = verdictsFor(log, n);
+  // ⟨q-5a93c2d7⟩ — the pre-merge question, same predicate, both channels.
+  const gate = gatedBy([...busVerdicts.map((v) => ({ ...v, channel: "bus" as const })), ...prVerdictsIn(f.comments ?? [])], head, null);
   if (!gate.gated) {
     const named = (gate.crossed ?? []).map((c) => c.gatedSha.slice(0, 7)).join(", ");
     return {
@@ -1501,7 +1773,7 @@ export async function mergeTool(
   }
 
   if (!args.write)
-    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass, and head ${head.slice(0, 7)} is gated by a PASS from ${gate.by.from}. Pass write:true to apply.` };
+    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass, and head ${head.slice(0, 7)} is gated by a PASS from ${gate.gater}${gate.attribution === "account" ? " (the PR's shared account — no bus verdict names a seat)" : ""}. Pass write:true to apply.` };
 
   doMerge(repo, n, args.method ?? "squash");
   return { ok: true as const, merged: true as const, verdict };