agent-coord-mcp 0.26.21 → 0.26.22

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,16 +30,20 @@ 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";
 
 const QUEUE_DOC = "docs/QUEUE.md";
@@ -160,6 +164,7 @@ 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;
@@ -287,18 +292,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.
+ *
+ * ⚠ 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.
  *
- * 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.
+ * 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 +367,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 +413,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 +502,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 +511,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 +524,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 +672,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 +744,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 +787,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 +948,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;
@@ -926,6 +1051,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 +1100,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}`;
@@ -1129,10 +1293,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 +1328,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 +1369,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 +1462,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 +1483,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 +1491,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 +1526,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 +1693,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 +1711,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 };

package/src/tools/registry.ts

@@ -2,10 +2,11 @@ import { detachAgentTool } from "./transport.js";
 import { isLocallyProbeable, isRemoteTmuxKind, targetOf } from "../transports/index.js";
 import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
-import { existsSync, openSync, watch } from "node:fs";
+import { existsSync, openSync, statSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { detectSpread, installedBuild } from "../server-spread.js";
 import { z } from "zod";
 import path from "node:path";
 import {
@@ -53,7 +54,8 @@ import {
   type RoomRegistry,
   type SessionBinding,
 } from "../store.js";
-import { recordAuthorityFor, resolveRole, CANONICAL_ROLE_IDS, roleInputSchema, type RoleArg } from "../roles.js";
+import { recordAuthorityFor, resolveRole, CANONICAL_ROLE_IDS, roleInputSchema, isHuman, type RoleArg } from "../roles.js";
+import { readHumans, recordHuman } from "../store.js";
 import {
   type AgentEntry,
   type AgentRegistry,
@@ -180,6 +182,10 @@ export async function registerTool(args: {
     return current;
   });
   const entry = reg[args.agentId];
+  // ⟨q-178878aa⟩ — a HUMAN registration is recorded durably: the registry entry itself is
+  // evicted after EVICT_MS (no heartbeat, no transport), and the send path's exemption
+  // must still see the human after that.
+  if (isHuman(entry)) await recordHuman(args.agentId, { displayName: entry.role, by: `register:${args.agentId}` });
   // Echo the record types this role may and may not emit. Record authority is
   // otherwise invisible until the first typed send is refused mid-work — this
   // is how an agent whose role owns `go`/`scope`/`verdict` finds out at
@@ -287,6 +293,23 @@ export async function heartbeatTool(args: { agentId: string }) {
       return current;
     }
     current[args.agentId].lastHeartbeat = Date.now();
+    /*
+     * ⛔ STAMP THE ANSWERING PROCESS — `⟨q-cec42e20⟩`. This runs INSIDE the server that
+     * is answering, which is the only place these two facts exist: `capabilities`
+     * reports them solely to its own caller, and no seat can query another seat's
+     * server at all. Publishing them here is what makes a cross-seat comparison
+     * possible without every seat having to volunteer it in prose.
+     *
+     * `startedAt` is derived from uptime rather than read from a file: an mtime tracks
+     * writes (a reinstall of identical bytes moves it) while uptime is a fact about
+     * THIS process.
+     */
+    current[args.agentId].serverPid = process.pid;
+    current[args.agentId].serverStartedAt = Date.now() - Math.round(process.uptime() * 1000);
+    // ⛔ WHAT this process is executing, not what it is labelled. Resolved from this
+    // module's own URL, so a server running a dev `dist/` says so instead of inheriting
+    // the installed path — the case that made a 3-build fleet read AGREED.
+    current[args.agentId].serverModule = installedBuild(import.meta.url, statSync)?.module;
     return current;
   });
   if (missing) return { ok: false, error: `agent '${args.agentId}' not registered` };
@@ -331,6 +354,8 @@ export async function listAgentsTool() {
       // heartbeat. This stamp only ever overwrote a true value with a
       // simultaneous one.
       if (liveTransports.has(id)) continue;
+      // A human has no heartbeat to go stale; evicting one is how the exemption went blind.
+      if (isHuman(entry)) continue;
       if (now - entry.lastHeartbeat > EVICT_MS) {
         evicted.push(id);
         delete current[id];
@@ -417,7 +442,33 @@ export async function listAgentsTool() {
       "granted to the SENDER and paid by every READER: their multi-line messages cannot be slimmed. " +
       "A rising share means the rule is decaying.",
   };
-  return { agents, evicted, proseOnly };
+  /*
+   * ⛔⛆ AND WHETHER THOSE SEATS AGREE ABOUT WHAT THEY ARE RUNNING — `⟨q-cec42e20⟩`.
+   *
+   * Reported HERE because this is the verb that already answers "who is live", and the
+   * spread is a property of that same population: a reader asking who is on the bus is
+   * exactly the reader who needs to know their servers are not the same build.
+   *
+   * ⚠ IT NEVER REPORTS AGREEMENT IT DID NOT ESTABLISH. A seat that has not stamped its
+   * identity is UNCOMPARABLE and poisons the verdict to CANNOT_COMPARE rather than being
+   * dropped from the population — because "every seat I could read agrees" and "the
+   * fleet agrees" are different claims, and only the second is what a reader will act on.
+   */
+  const spread = detectSpread(
+    Object.values(reg)
+      .filter((a) => liveTransports.has(a.agentId) || now - a.lastHeartbeat < STALE_MS)
+      .map((a) => ({
+        agentId: a.agentId,
+        serverPid: a.serverPid,
+        serverStartedAt: a.serverStartedAt,
+        serverModule: a.serverModule,
+      })),
+    installedBuild(import.meta.url, statSync),
+  );
+
+  // ⟨q-178878aa⟩ — the humans the bus knows: visible here, read at send time, never evicted.
+  const humans = Object.entries(await readHumans()).map(([id, h]) => ({ id, ...h }));
+  return { agents, evicted, proseOnly, humans, serverSpread: spread };
 }
 
 /**