agent-coord-mcp 0.26.20 → 0.26.22

package/src/tools/records.ts

@@ -12,9 +12,11 @@
  * 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";
+
+import { treeProvenance } from "./tree-provenance.js";
 import {
   parseWorkDoc,
   renderWorkDoc,
@@ -28,14 +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, 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";
@@ -156,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;
@@ -283,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?
  *
- * 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.
+ * ⛔⛆ 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.
+ *
+ * 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
@@ -305,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;
 }
 
 /**
@@ -341,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.
@@ -387,8 +459,15 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     };
   }
   const repo = args.repo ?? process.cwd();
+  // ⛔⛆ SAY WHICH TREE THIS ANSWER CAME FROM (⟨q-c1af2db3⟩). This verb reads
+  // `docs/QUEUE.md` out of a working tree nobody owns, and a stale one produced
+  // a confidently wrong routing decision in both directions inside ten minutes —
+  // a row ruled un-claimable from a stale file, and a worker told to hold on a
+  // row that was already split. The answer was well-formed and said nothing
+  // about its source, which is what made it invisible.
+  const tree = treeProvenance(repo);
   const q = readDoc(repo, QUEUE_DOC);
-  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'`, tree };
   const items = queueItemsOf(q.doc);
   // The seam's own count of unticked rows — the number every axis must add back
   // up to. Taken BEFORE any exclusion so it cannot inherit one.
@@ -423,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 ?? "";
@@ -432,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));
@@ -443,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
@@ -533,6 +626,10 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // the severity finding one file over. Say the axis is uninformative instead.
   const undiscriminating = silent.length === open.length && open.length > 1;
   return {
+    // ⛔ THE PROVENANCE TRAVELS WITH THE ANSWER, not in a second call. A
+    // routing answer whose tree is unnamed is the defect this row exists for.
+    tree,
+    ...(tree.warning ? { staleWarning: tree.warning } : {}),
     ok: true as const,
     project: args.project,
     open: open.length,
@@ -575,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})`,
       ),
     ],
@@ -647,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 {
@@ -683,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,
@@ -822,7 +944,47 @@ export const landSchema = {
   result: z.string().optional(),
 };
 
-export async function landTool(args: {
+/**
+ * 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 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,comments"], {
+      cwd: repo,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    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),
+      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;
   pr: string;
   queueItemId?: string;
@@ -830,7 +992,10 @@ export async function landTool(args: {
   base?: string;
   write?: boolean;
   result?: string;
-}) {
+},
+  readMergeFacts: ReadMergeFacts = ghMergeFacts,
+  readVerdictLog: ReadVerdictLog = roomLog,
+) {
   const repo = args.repo ?? process.cwd();
   const base = args.base ?? "main";
   const n = prNumber(args.pr);
@@ -886,6 +1051,17 @@ export async function landTool(args: {
   // `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}'` };
 
@@ -924,7 +1100,35 @@ export async function landTool(args: {
     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}`;
@@ -945,8 +1149,41 @@ export async function landTool(args: {
   const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
   const summary = originalText !== null ? summarize(originalText) : null;
 
+  /*
+   * ⛔⛆⛆ THE ROW'S ID LEADS THE ENTRY, BECAUSE A TRUNCATED HEADLINE CANNOT CARRY IT
+   * — `⟨q-d046204d⟩`.
+   *
+   * `summarize` cuts at 96 characters and appends `…`. The sigil was never omitted
+   * from these entries: IT WAS CUT, because in the row it sits later than the
+   * truncation point. So the entry came out with a PERFECT `ref` slot and a `text`
+   * that names no row — and `closingRefs` needs BOTH halves, so the row reads
+   * untied and `main` goes red. `⟨q-c1af2db3⟩` at `17a9ffc` is that, measured.
+   *
+   * ⭐⭐ THE FIX IS POSITION, NOT LENGTH. Putting the id BEFORE the summary takes it
+   * out of the truncated region BY CONSTRUCTION, so it survives any headline length
+   * — where raising `max` only moves the cliff. The row is explicit that "write
+   * longer headlines" is not an acceptable fix, and it is right: a length that is
+   * enough today is a truncation tomorrow.
+   *
+   * ✅ AND THE CONSUMER ALREADY EXPECTS THIS SPELLING. `doneRecordsDelivery` strips
+   * a leading `⟨q-…⟩` before comparing, and says why: "an entry written as `⟨id⟩
+   * <summary>` and one written as `<summary>` agree". So the composed-summary arm
+   * keeps matching and this needed no change there.
+   *
+   * ⚠ THIS IS NOT THE ARM `⟨q-4a1e70c5⟩` REMOVED, and the difference is the whole
+   * reason this is safe. That arm INFERRED delivery from a sigil appearing ANYWHERE
+   * in an entry — a reader-side guess that produced eleven false positives, because
+   * this repo's canon requires entries to cite item ids for other reasons. This
+   * writes the id in a DETERMINISTIC LEADING POSITION so the tie can be read. It
+   * infers nothing, and re-reading a sigil as "delivered" is still wrong.
+   *
+   * The id is the ITEM's, taken from the record rather than re-derived: `target` is
+   * non-null whenever `summary` is, since the summary comes from its text.
+   */
   const doneLine =
-    already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
+    already || !summary || !target
+      ? null
+      : `- [x] ⟨${target.id}⟩ ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
 
   // APPEND TO DONE.md — the half this verb exists for.
   //
@@ -1034,12 +1271,75 @@ export async function landTool(args: {
     }
   }
 
+  /*
+   * ⛔⛆ SECOND LINE: WAS THE THING MERGED THE THING GATED? (kit#268, ⟨q-6a4f0c38⟩)
+   *
+   * `merge` refuses this BEFORE the fact and is the control that prevents. This
+   * one runs after, and its job is different: it is how the fleet LEARNS a
+   * crossing happened anyway — through a merge done by hand, by `gh` directly,
+   * or by a seat that never called the verb.
+   *
+   * It REPORTS and never refuses. A closure is not the right place to litigate a
+   * merge that already happened: the verdict is QA's artefact, the merge may have
+   * been someone else's, and blocking the record would leave the work landed and
+   * unrecorded — strictly worse than landed and recorded with a flag on it.
+   *
+   * ⚠ AND IT SAYS SO WHEN IT COULD NOT LOOK. An omitted field reads as "fine".
+   */
+  const gatedHead = (() => {
+    const mf = readMergeFacts(repo, n);
+    if (!mf) return { checked: false as const, note: `could not read #${n}'s merged head and merge time — whether the merged head was gated is UNKNOWN, not clean.` };
+    const log = readVerdictLog(args.project);
+    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: 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) {
+      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,
+      gated: false as const,
+      head: mf.headRefOid.slice(0, 8),
+      reason: a.reason,
+      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 no typed verdict bound to the merged head exists in any channel.` +
+        (unparsed ? ` (${unparsed} log line(s) unreadable and skipped.)` : ""),
+    };
+  })();
+
   return {
     ok: true as const,
     project: args.project,
     pr: `#${n}`,
     comparedAgainst: ref,
     landedIn: landedIn.slice(0, 8),
+    gatedHead,
     // 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.
@@ -1069,6 +1369,11 @@ export async function landTool(args: {
     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
       ? {}
       : {
@@ -1151,13 +1456,17 @@ export type PrFacts = {
   state: string;
   mergeable: string;
   checks: unknown[];
+  /** The branch tip RIGHT NOW — what would actually be merged (⟨q-6a4f0c38⟩). */
+  headRefOid?: string;
   /** Unified diff of the PR, for the ticked-box audit. */
   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"], {
+  const out = execFileSync("gh", ["pr", "view", n, "--json", "state,mergeable,statusCheckRollup,headRefOid"], {
     cwd: repo,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "ignore"],
@@ -1174,13 +1483,15 @@ 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");
   return {
     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"),
@@ -1206,10 +1517,43 @@ const ghMerge: DoMerge = (repo, n, method) => {
   });
 };
 
+/**
+ * The room log, injected for the same reason `doMerge` is: a test must be able to
+ * drive every refusal branch without this host's ~/agent-coord.
+ *
+ * Returns null when the log cannot be read — distinct from "" (read, and empty),
+ * because "no verdicts recorded" and "could not look" are different answers and
+ * 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 {
+    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;
+  }
+};
+
 export async function mergeTool(
   args: { project: string; pr: string; repo?: string; method?: string; write?: boolean },
   facts: (repo: string, n: string) => PrFacts = ghFacts,
   doMerge: DoMerge = ghMerge,
+  readVerdictLog: ReadVerdictLog = roomLog,
 ) {
   const repo = args.repo ?? process.cwd();
   const n = prNumber(args.pr);
@@ -1318,8 +1662,56 @@ export async function mergeTool(
   if (f.mergeable === "CONFLICTING")
     return { ok: false as const, error: `#${n} is CONFLICTING with its base.`, verdict };
 
+  /*
+   * ⛔⛆ THE THING MERGED MUST BE THE THING GATED — kit#268, ⟨q-6a4f0c38⟩.
+   *
+   * A PASS was posted for `6051193` at 10:23:14Z; the merge ran 8 seconds later
+   * and took `1d6deab`, because the author force-pushed in between. Checks were
+   * green on BOTH heads, so every refusal above passed honestly. Nothing asked
+   * the only question that mattered: is the head in front of me the head the
+   * verdict named?
+   *
+   * THIS IS THE FIRST-LINE CONTROL because it PREVENTS. The recording step can
+   * only report afterwards. It sits before the dry-run return on purpose: a dry
+   * run must say it would refuse, or the preview disagrees with the act.
+   */
+  const head = f.headRefOid ?? "";
+  if (!head) {
+    return {
+      ok: false as const,
+      error: `could not read #${n}'s current head — NOT read, which is not the same as read and matching the verdict.`,
+      verdict,
+    };
+  }
+  const log = readVerdictLog(args.project);
+  if (log === null) {
+    return {
+      ok: false as const,
+      error:
+        `could not read the verdict log for project '${args.project}' — so whether #${n}'s head ${head.slice(0, 7)} ` +
+        `was ever gated is UNKNOWN, and unknown is not gated.`,
+      verdict,
+    };
+  }
+  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 {
+      ok: false as const,
+      error:
+        `#${n}'s head is ${head.slice(0, 7)} and ${gate.reason}. ` +
+        (named ? `Gated instead: ${named}. ` : "") +
+        `Re-gate this head before merging — a PASS that must be re-issued is cheap, a merge nobody gated is not.` +
+        (unparsed ? ` (${unparsed} log line(s) unreadable and skipped.)` : ""),
+      verdict,
+      gatedHead: { head, gated: false as const, reason: gate.reason },
+    };
+  }
+
   if (!args.write)
-    return { ok: true as const, merged: false as const, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass. 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 };