agent-coord-mcp 0.26.20 → 0.26.22

package/dist/tools/records.js

@@ -12,13 +12,16 @@
  * 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 { parseWorkDoc, renderWorkDocForWrite, queueItemsOf, doneEntriesOf, phaseCitationsDetailed, newlyTickedInDiff, sweepTagOf, awaitingOf, refsIn, refsMatch, workstreamsV1RowsOf, } from "@davidbalzan/groundwork-seam";
+import { treeProvenance } from "./tree-provenance.js";
+import { parseWorkDoc, renderWorkDocForWrite, queueItemsOf, doneEntriesOf, phaseCitationsDetailed, newlyTickedInDiff, sweepTagOf, awaitingOf, refsIn, closingCitation, refsMatch, workstreamsV1RowsOf, workStateOf, declarationOf, } 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 } from "./events.js";
 const QUEUE_DOC = "docs/QUEUE.md";
 const DONE_DOC = "docs/DONE.md";
@@ -249,18 +252,60 @@ export function noDownstream(items) {
 function rowSubjectIds(row) {
     return [...String(row.stream).matchAll(/\b(q-[0-9a-f]{8})\b/g)].map((m) => m[1]);
 }
+/*
+ * ⭐ 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, status) {
+    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
@@ -271,16 +316,24 @@ function rowSubjectIds(row) {
  * 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, id, text) {
+function boardHoldOf(rows, id, text) {
     const key = keyOf({ text }).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;
 }
 /**
  * Is this DONE entry the RECORD OF THIS ITEM CLOSING, rather than an entry that
@@ -308,7 +361,7 @@ function boardHoldsItem(rows, id, text) {
  * 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.
@@ -351,9 +404,16 @@ export async function nextUnblockedTool(args) {
         };
     }
     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, error: `no ${QUEUE_DOC} under '${repo}'` };
+        return { ok: false, 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.
@@ -397,20 +457,34 @@ export async function nextUnblockedTool(args) {
         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");
+        // 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, "done");
+            deliveredBy.set(i.id, { reason: "done" });
     }
     const open = items.filter((i) => !i.done && !deliveredBy.has(i.id));
     // 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", 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", 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
     // two rows with identical text carry the SAME id — verified: `- [ ] (P1) an
@@ -500,6 +574,10 @@ export async function nextUnblockedTool(args) {
     // 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,
         project: args.project,
         open: open.length,
@@ -541,7 +619,7 @@ export async function nextUnblockedTool(args) {
             ...awaitingDecision.map((a) => `⏸ skipped — awaiting decision from ${a.who} (${a.id})`),
             ...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})`),
         ],
         // A SEPARATE AXIS, deliberately. See noDownstream().
@@ -608,6 +686,13 @@ 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) {
     const halt = haltState();
@@ -646,6 +731,25 @@ export async function claimTool(args) {
     // 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: "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, 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,
@@ -776,7 +880,42 @@ export const landSchema = {
     /** One-line result, written after the citation on the closed item's line. */
     result: z.string().optional(),
 };
-export async function landTool(args) {
+const ghMergeFacts = (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);
+        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, n) {
+    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, readMergeFacts = ghMergeFacts, readVerdictLog = roomLog) {
     const repo = args.repo ?? process.cwd();
     const base = args.base ?? "main";
     const n = prNumber(args.pr);
@@ -831,6 +970,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, error: `no queue item with id '${args.queueItemId}'` };
@@ -869,7 +1019,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 = 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}`;
@@ -887,7 +1065,40 @@ export async function landTool(args) {
     // as UNDER-QUALIFIED rather than silently written.
     const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
     const summary = originalText !== null ? summarize(originalText) : null;
-    const doneLine = already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
+    /*
+     * ⛔⛆⛆ 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 || !target
+        ? null
+        : `- [x] ⟨${target.id}⟩ ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
     // APPEND TO DONE.md — the half this verb exists for.
     //
     // The first `write:true` run closed the queue item and wrote NOTHING to
@@ -978,12 +1189,76 @@ export async function landTool(args) {
             events = { emitted: [ev], deliveries, refused: [] };
         }
     }
+    /*
+     * ⛔⛆ 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, 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, 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, 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" })), ...prVerdictsIn(mf.comments ?? [])];
+        const a = gatedBy(verdicts, mf.headRefOid, at);
+        if (a.gated) {
+            const late = (a.lateByMs ?? 0) > 0;
+            return {
+                checked: true,
+                gated: true,
+                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,
+            gated: false,
+            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,
         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.
@@ -1012,6 +1287,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
             ? {}
             : {
@@ -1063,7 +1343,7 @@ export const mergeSchema = {
     write: z.boolean().optional(),
 };
 const ghFacts = (repo, n) => {
-    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"],
@@ -1081,13 +1361,15 @@ const ghFacts = (repo, n) => {
     // 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"]) || "{}");
+    const meta = JSON.parse(gh(["pr", "view", n, "--json", "title,body,commits,comments"]) || "{}");
     const subjects = (meta.commits ?? [])
         .map((c) => c.messageHeadline ?? "")
         .join("\n");
     return {
         state: String(j.state ?? ""),
         mergeable: String(j.mergeable ?? ""),
+        headRefOid: String(j.headRefOid ?? ""),
+        comments: (meta.comments ?? []).map((c) => ({ body: String(c.body ?? ""), createdAt: c.createdAt, author: c.author?.login })),
         checks: j.statusCheckRollup ?? [],
         diff: gh(["pr", "diff", n]),
         citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
@@ -1100,7 +1382,31 @@ const ghMerge = (repo, n, method) => {
         stdio: ["ignore", "pipe", "ignore"],
     });
 };
-export async function mergeTool(args, facts = ghFacts, doMerge = ghMerge) {
+/**
+ * ⟨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 = (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, facts = ghFacts, doMerge = ghMerge, readVerdictLog = roomLog) {
     const repo = args.repo ?? process.cwd();
     const n = prNumber(args.pr);
     if (!n)
@@ -1197,8 +1503,53 @@ export async function mergeTool(args, facts = ghFacts, doMerge = ghMerge) {
     }
     if (f.mergeable === "CONFLICTING")
         return { ok: false, 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,
+            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,
+            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" })), ...prVerdictsIn(f.comments ?? [])], head, null);
+    if (!gate.gated) {
+        const named = (gate.crossed ?? []).map((c) => c.gatedSha.slice(0, 7)).join(", ");
+        return {
+            ok: false,
+            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, reason: gate.reason },
+        };
+    }
     if (!args.write)
-        return { ok: true, merged: false, verdict, note: `#${n} would merge: all ${checks.length} check(s) pass. Pass write:true to apply.` };
+        return { ok: true, merged: false, 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, merged: true, verdict };
 }