agent-coord-mcp 0.26.19 → 0.26.21

package/dist/tools/records.js

@@ -15,8 +15,11 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
+import { treeProvenance } from "./tree-provenance.js";
 import { parseWorkDoc, renderWorkDocForWrite, queueItemsOf, doneEntriesOf, phaseCitationsDetailed, newlyTickedInDiff, sweepTagOf, awaitingOf, refsIn, refsMatch, workstreamsV1RowsOf, } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
+import { ROOT } from "../store.js";
+import { verdictsFor, gatedAt } from "../gated-head.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState, isInFlightStatus } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived } from "./events.js";
@@ -51,11 +54,77 @@ const readDoc = (repo, rel) => {
  * Returns what it stamped so the caller can report it rather than leaving an
  * absorbing writer to find it in a diff.
  */
-function writeDoc(repo, rel, doc, original) {
+/**
+ * A WRITE WHOSE BASE MOVED UNDER IT. Thrown, never returned, because a refusal
+ * that can be ignored is how the silent loss happened in the first place.
+ */
+export class StaleWriteError extends Error {
+    rel;
+    detail;
+    alreadyWritten;
+    constructor(rel, detail, alreadyWritten) {
+        super(`refusing to write ${rel}: it changed on disk after this call read it (${detail}). ` +
+            `Nothing was overwritten. Re-read and retry.` +
+            (alreadyWritten.length ? ` ALREADY WRITTEN by this call: ${alreadyWritten.join(", ")} — that write stands.` : ""));
+        this.rel = rel;
+        this.detail = detail;
+        this.alreadyWritten = alreadyWritten;
+        this.name = "StaleWriteError";
+    }
+}
+/** What moved, in terms a caller can act on without diffing the file itself. */
+function describeDrift(original, current) {
+    const ol = original.split("\n");
+    const cl = current.split("\n");
+    let i = 0;
+    while (i < ol.length && i < cl.length && ol[i] === cl[i])
+        i++;
+    return (`${ol.length} → ${cl.length} line(s), ${original.length} → ${current.length} byte(s)` +
+        (i < Math.max(ol.length, cl.length) ? `, first difference at line ${i + 1}` : ""));
+}
+/**
+ * ⛔ COMPARE-AND-SWAP, AND THE RE-READ IS THE WHOLE POINT.
+ *
+ * This function used to compare the rendered text against `original` — the
+ * caller's IN-MEMORY snapshot from when it read — and then write. It never looked
+ * at the file again. Anything written in between was clobbered with no error, no
+ * diff, and nothing in the return value: `{ written: true }` came back for a
+ * write that had destroyed someone else's row.
+ *
+ * Measured before fixing: two writers taking the same original and both
+ * committing leave TWO rows where three should be, and the first writer's row is
+ * simply gone. This is not hypothetical — four processes write these documents
+ * (the aide from its own clone, `claim`, `land`, worker seats), and `land --write`
+ * ran six times in one afternoon against a queue the aide was editing.
+ *
+ * So the file is re-read immediately before the write and must still match what
+ * the caller read. On a mismatch this REFUSES — loudly, by throwing — and names
+ * what moved. A refused write is recoverable; a silent overwrite is not, and the
+ * loser of the race never learns it lost.
+ *
+ * What this does NOT claim: it is not a lock. Two processes can still interleave
+ * between this re-read and the `writeFileSync` a few microseconds later. The
+ * window goes from "the whole duration of the caller's work" — parsing, git
+ * calls, composing a line — down to two adjacent statements. That is a large
+ * reduction and not zero, and a lock is the stronger fix if this ever proves
+ * insufficient.
+ *
+ * EXPORTED FOR TESTS, deliberately. The race it guards is BETWEEN PROCESSES —
+ * the aide's clone, `claim`, `land` — and `landTool` runs synchronously from its
+ * read to its write, so no in-process test can interleave them. An end-to-end
+ * attempt passed identically with the guard removed, i.e. it proved nothing. A
+ * data-loss guard is worth a narrow export to be testable at the level it lives.
+ */
+export function writeDoc(repo, rel, doc, original, alreadyWritten = []) {
     const { text, stamped } = renderWorkDocForWrite(doc);
     if (text === original)
         return { written: false, stamped: [] };
-    writeFileSync(path.join(repo, rel), text);
+    const p = path.join(repo, rel);
+    const current = existsSync(p) ? readFileSync(p, "utf8") : "";
+    if (current !== original) {
+        throw new StaleWriteError(rel, describeDrift(original, current), alreadyWritten);
+    }
+    writeFileSync(p, text);
     return { written: true, stamped };
 }
 const git = (repo, args) => execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -125,6 +194,15 @@ export function summarize(text, max = 96) {
  * the queue SAYS it waits on this", never "nothing waits on this".
  */
 export function noDownstream(items) {
+    // ⚠ THE SECOND `!i.done` IN THIS FILE, AND IT IS DELIBERATE — the reconciliation
+    // asked for by ⟨q-7d2e04b8⟩. `nextUnblockedTool` passes an ALREADY-FILTERED
+    // list, so this re-filter is a no-op on that path; it is kept because this
+    // function is EXPORTED and its contract is "given items, which have nothing
+    // waiting on them", which must hold for a caller that hands it raw items.
+    //
+    // The two are not the same predicate and must not be merged: this one is
+    // `!done`, while the router's also subtracts the delivery join. Collapsing
+    // them would make an exported helper inherit a routing policy.
     const open = items.filter((i) => !i.done);
     const named = new Set();
     for (const i of open) {
@@ -211,44 +289,53 @@ function boardHoldsItem(rows, id, text) {
  * Is this DONE entry the RECORD OF THIS ITEM CLOSING, rather than an entry that
  * merely MENTIONS it?
  *
- * `DONE.md` has no status cells, so the board's answer does not transfer and
- * this needs its own — and the item's own words for what it needs are that "the
- * canon rule must name its citations in a form the join can tell apart".
+ * ⛔ THE SIGIL ARM WAS REMOVED ⟨q-4a1e70c5⟩. It answered yes whenever `⟨id⟩`
+ * appeared ANYWHERE in an entry, on a census that had inverted: today
+ * `docs/DONE.md` carries more sigil mentions than bare ones, because `⟨id⟩` is the
+ * house spelling everything else teaches — so the COMPLIANT way to cite an item
+ * became the spelling that meant "delivered". Measured before removal, on 143
+ * open rows: ELEVEN false positives, ZERO independent true positives (every row
+ * it correctly excluded was already excluded by `!i.done`, which runs first), and
+ * a MISS on its own founding case — the row recorded as q-b4e7c209 had its work
+ * merged under a different row's citation, stayed `[ ]`, and was offered as top
+ * P1 twice.
  *
- * MEASURED ON THE REAL `DONE.md` @17b72ff, which settles which form is which:
- * BRACKETED ids appear ZERO times; all ELEVEN id mentions are BARE, in prose,
- * inside backticks — every one of them a citation. So:
+ * ⚠ THE SPELLING RULE DID NOT FAIL BECAUSE THE SPELLING FLIPPED. IT FAILED
+ * BECAUSE SPELLING WAS NEVER THE SIGNAL. Entries name item ids for several
+ * reasons this repo's own canon REQUIRES — a residual gap must cite its queue
+ * item — so no reading of that file separates a closure from a mention. Three
+ * replacements were measured and each was worse or equal: position does not
+ * discriminate (a known-false and a known-true entry are structurally identical,
+ * and only 2 of 252 entries lead with a sigil); `DoneEntry.id` is a derived `d-`
+ * id, not the item's; and the citation-slot tie `queue-done-loop` uses gives 23
+ * false positives, because open rows cite refs as EVIDENCE.
  *
- *   DELIVERY  the entry carries the item's own COMPOSED SUMMARY — the
- *             deterministic form `land` writes, `summarize(item.text)` — or it
- *             names the item in the recorded-id sigil `⟨id⟩`, which is this
- *             corpus's "this IS that item" marker (it is how QUEUE.md records
- *             identity, and a human writing it in DONE.md means exactly that).
- *   CITATION  a BARE `q-xxxxxxxx` anywhere. This is the form our own shipped
- *             canon (q-912a67e8) produces: a `DONE` entry may name a residual
- *             gap but MUST CITE A QUEUE ITEM for it. Obeying that rule wrote an
- *             open item's id into `DONE.md`, and the substring join read the
- *             citation as delivery — a canon rule and a code path in direct
- *             contradiction, where COMPLIANCE with the canon triggered the
- *             defect. LIVE on origin/main, not latent: the part (a) entry for
- *             q-507e80c4 cites it exactly this way while part (b) is open work.
+ * ✅ WHAT SURVIVES IS THE COMPOSED-SUMMARY ARM, and it is a DIFFERENT EVIDENCE
+ * CLASS — the same distinction that keeps `boardHoldsItem`. 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.
  *
- * Note what is deliberately NOT the rule: a shared PR ref. `land` never writes
- * the item id into `DONE.md` at all (the summary excludes the `⟨id⟩` token), and
- * the live entry for q-507e80c4 cites `#219` while the item's own line cites no
- * PR — so a ref-tie would have marked a genuinely-open part (b) as delivered.
+ * ⚠ IT IS CURRENTLY UNEXERCISED BY THIS REPO'S CORPUS — 0 of 143 open, 0 of 9
+ * closed — AND THAT IS NOT EVIDENCE THAT IT IS DEAD. The cause is practice, not
+ * code: rows here are closed with `land --write` and the composed line is then
+ * OVERWRITTEN with hand-written prose, so the structural record it would match is
+ * destroyed within the minute. **Do not re-derive "dead code" from another zero
+ * count.** Its input returns the moment a closing entry keeps what `land` wrote.
+ *
+ * ⛔ AND WHAT IS NO LONGER GUARDED, because a removal that does not name its own
+ * cost is worse than the guard: A ROW WHOSE WORK MERGED UNDER ANOTHER ROW'S
+ * CITATION IS ELIGIBLE AGAIN, AND NOTHING IN `next_unblocked` WILL NOTICE.
+ * Accepted knowingly — the arm that claimed to cover it did not, on the one live
+ * instance it had. Closing such a row is coordinator discipline, not a predicate.
  */
 function doneRecordsDelivery(entries, id, text) {
     const norm = (v) => v.replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
     const target = norm(summarize(text)).replace(/…$/, "");
-    const sigil = `⟨${id}⟩`;
     return entries.some((e) => {
-        const t = String(e.text);
-        if (t.includes(sigil))
-            return true;
         // A leading recorded-id token is stripped before comparing, so an entry
         // written as `⟨id⟩ <summary>` and one written as `<summary>` agree.
-        const body = norm(t).replace(/^⟨q-[0-9a-f]{8}⟩\s*/, "");
+        const body = norm(String(e.text)).replace(/^⟨q-[0-9a-f]{8}⟩\s*/, "");
         return target.length >= 12 && body.startsWith(target);
     });
 }
@@ -267,10 +354,20 @@ 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.
+    const parsedOpen = items.filter((i) => !i.done).length;
     // ALREADY-DELIVERED ITEMS ARE NEVER RE-OFFERED, and `!i.done` alone does not
     // establish that.
     //
@@ -287,17 +384,68 @@ export async function nextUnblockedTool(args) {
     // (Task 21.1) are what make this join reliable — with a content-hash id the
     // board row and the DONE entry stopped matching the moment anyone reworded
     // the item, which is how the memory was lost in the first place.
-    const delivered = new Set();
+    // ⛔⛆ `delivered` IS A REASON, NOT AN ERASURE (⟨q-7d2e04b8⟩). This set used to
+    // be subtracted from `open` BEFORE any axis ran, so an item it excluded could
+    // appear on NO axis by construction — the one guarantee this verb's contract
+    // makes is that it never skips silently, and this was the one path that did.
+    //
+    // MEASURED on the live queue at `a032069`: the file held 143 open rows, the
+    // seam parsed all 143, and this verb reported `open: 129`. Its declared axes
+    // accounted for ONE. Fourteen rows were outside the router's universe and
+    // nothing in the response said so — invisible from the only seat that would
+    // notice, because a worker asking for the next item still gets a real one.
+    //
+    // ⚠ 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();
     const doneDoc = readDoc(repo, DONE_DOC);
     const boardDoc = readDoc(repo, BOARD_DOC);
     const boardText = boardDoc?.text ?? "";
     const doneEntries = doneDoc ? doneEntriesOf(doneDoc.doc) : [];
     const boardRows = boardDoc ? workstreamsV1RowsOf(boardDoc.doc) : [];
     for (const i of items) {
-        if (boardHoldsItem(boardRows, i.id, String(i.text)) || doneRecordsDelivery(doneEntries, i.id, String(i.text)))
-            delivered.add(i.id);
+        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");
     }
-    const open = items.filter((i) => !i.done && !delivered.has(i.id));
+    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.
+    const delivered = items
+        .filter((i) => !i.done && deliveredBy.has(i.id))
+        .map((i) => ({ item: keyOf(i), id: i.id, reason: deliveredBy.get(i.id) }));
+    // ⛔⛆ 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
+    // identical row` twice yields `q-c9f3ded8` twice.
+    //
+    // Everything downstream is keyed by id, so ONE delivery record then excludes
+    // BOTH rows: measured on a fixture, a single DONE entry took `parsedOpen: 3`
+    // to `offered: 1`. The accounting still reconciles — both are named — so the
+    // self-check above CANNOT catch it, which is exactly why it needs its own axis
+    // rather than a flag on `reconciles`.
+    //
+    // ⭐ WHY THIS AXIS AND NOT A COUNT: a MISSING row can always be argued to be a
+    // filter working as designed; a row reported TWICE cannot be anything but the
+    // accounting. It is the one symptom here that does not rest on a count.
+    const idCounts = new Map();
+    for (const i of items)
+        if (!i.done)
+            idCounts.set(i.id, (idCounts.get(i.id) ?? 0) + 1);
+    const duplicateIds = [...idCounts.entries()]
+        .filter(([, n]) => n > 1)
+        .map(([id, rows]) => ({
+        id,
+        rows,
+        why: `${rows} open rows share the id ${id} — stable ids are derived from row TEXT, so identical rows collide. Every axis here is keyed by id, so one delivery record excludes all ${rows}. Reword one row to separate them.`,
+    }));
     const ranked = open
         .map((i, idx) => ({ i, idx }))
         .sort((a, b) => (PRIORITY_ORDER[a.i.priority ?? "P3"] ?? 3) - (PRIORITY_ORDER[b.i.priority ?? "P3"] ?? 3) || a.idx - b.idx);
@@ -362,9 +510,33 @@ 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,
+        // ⛔ THE SELF-CHECK, because the defect this replaces was a NUMBER NOTHING
+        // EXPLAINED and the only thing that ever caught it was someone counting the
+        // file by hand. `parsedOpen` is every unticked row the seam sees; `offered`
+        // is what routing considered; `excluded` is what the axes account for. When
+        // `reconciles` is false, rows have left the universe with no named cause —
+        // the exact condition that was previously unobservable from the response.
+        //
+        // ⚠ IT REPORTS RATHER THAN THROWS: a router that refuses to hand out work
+        // because its own bookkeeping is off strands every lane, which is worse than
+        // the miscount. The caller gets a real item AND the discrepancy.
+        accounting: {
+            parsedOpen,
+            offered: open.length,
+            excluded: delivered.length,
+            reconciles: parsedOpen === open.length + delivered.length,
+        },
+        // A NAMED AXIS, not a subtraction. See the comment at `deliveredBy`.
+        delivered,
+        // A ROW REPORTED TWICE CANNOT BE A FILTER WORKING AS DESIGNED. See above.
+        duplicateIds,
         next: pick ? { id: pick.id, priority: pick.priority, text: pick.text } : null,
         skipped,
         // A SEPARATE AXIS from `skipped` (blocked) — this is "not this caller's
@@ -381,6 +553,10 @@ export async function nextUnblockedTool(args) {
             ...skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
             ...notClaimable.map((s) => `⏭ skipped — not worker-claimable (${s.sweepTag})`),
             ...awaitingDecision.map((a) => `⏸ skipped — awaiting decision from ${a.who} (${a.id})`),
+            ...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 — delivery recorded in DONE.md (${d.id})`),
         ],
         // A SEPARATE AXIS, deliberately. See noDownstream().
         noDownstream: undiscriminating
@@ -614,7 +790,23 @@ 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"], {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const j = JSON.parse(out);
+        if (!j.headRefOid || !j.mergedAt)
+            return null;
+        return { headRefOid: String(j.headRefOid), mergedAt: String(j.mergedAt) };
+    }
+    catch {
+        return null;
+    }
+};
+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);
@@ -725,7 +917,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
@@ -739,40 +964,56 @@ export async function landTool(args) {
     // an entry added to the record model renders through the pinned glyph contract.
     const wrote = [];
     let stampedNotSupplied = [];
-    if (args.write) {
-        if (queueChanged) {
-            const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text);
-            if (w.written)
-                wrote.push(QUEUE_DOC);
-            // Rows stamped that this call did not ask to touch. `queueItemId` is the
-            // one item the caller supplied, so anything else here is a row that
-            // arrived unstamped from somewhere: the absorption this verb would
-            // otherwise carry to main under its own name.
-            stampedNotSupplied = w.stamped.filter((id) => id !== args.queueItemId);
-        }
-        if (doneLine) {
-            const blocks = d.doc.blocks;
-            let last = -1;
-            for (let i = 0; i < blocks.length; i++)
-                if (blocks[i]?.kind === "done")
-                    last = i;
-            if (last === -1) {
-                return {
-                    ok: false,
-                    error: `${DONE_DOC} has no parsed done block to append to — refusing to guess where the entry goes. A DONE.md that parses to zero entries is a defect in the log, not an empty log.`,
-                };
+    // A stale-base refusal is a RESULT, not a crash: the caller needs to know
+    // nothing was clobbered, what moved, and what this call had already written
+    // before it stopped. Thrown inside writeDoc so it cannot be ignored; converted
+    // here so the verb still answers.
+    try {
+        if (args.write) {
+            if (queueChanged) {
+                const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote);
+                if (w.written)
+                    wrote.push(QUEUE_DOC);
+                // Rows stamped that this call did not ask to touch. `queueItemId` is the
+                // one item the caller supplied, so anything else here is a row that
+                // arrived unstamped from somewhere: the absorption this verb would
+                // otherwise carry to main under its own name.
+                stampedNotSupplied = w.stamped.filter((id) => id !== args.queueItemId);
             }
-            const block = blocks[last];
-            const parsed = parseWorkDoc(`## Done\n${doneLine}\n`);
-            const entry = doneEntriesOf(parsed)[0];
-            if (!entry) {
-                return { ok: false, error: `the composed DONE line does not parse as done.v1: ${doneLine}` };
+            if (doneLine) {
+                const blocks = d.doc.blocks;
+                let last = -1;
+                for (let i = 0; i < blocks.length; i++)
+                    if (blocks[i]?.kind === "done")
+                        last = i;
+                if (last === -1) {
+                    return {
+                        ok: false,
+                        error: `${DONE_DOC} has no parsed done block to append to — refusing to guess where the entry goes. A DONE.md that parses to zero entries is a defect in the log, not an empty log.`,
+                    };
+                }
+                const block = blocks[last];
+                const parsed = parseWorkDoc(`## Done\n${doneLine}\n`);
+                const entry = doneEntriesOf(parsed)[0];
+                if (!entry) {
+                    return { ok: false, error: `the composed DONE line does not parse as done.v1: ${doneLine}` };
+                }
+                block.entries.push(entry);
+                if (writeDoc(repo, DONE_DOC, d.doc, d.text, wrote).written)
+                    wrote.push(DONE_DOC);
             }
-            block.entries.push(entry);
-            if (writeDoc(repo, DONE_DOC, d.doc, d.text).written)
-                wrote.push(DONE_DOC);
         }
     }
+    catch (e) {
+        if (e instanceof StaleWriteError) {
+            return {
+                ok: false,
+                error: e.message,
+                staleWrite: { doc: e.rel, drift: e.detail, alreadyWritten: e.alreadyWritten },
+            };
+        }
+        throw e;
+    }
     // 6.2 — EMIT ONLY AS A CONSEQUENCE OF THE RECORD CHANGING.
     //
     // Read back from disk, AFTER the write, and refuse to emit anything whose ref
@@ -800,12 +1041,54 @@ 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, unparsed } = verdictsFor(log, n);
+        const a = gatedAt(verdicts, mf.headRefOid, at);
+        if (a.gated) {
+            return { checked: true, gated: true, head: mf.headRefOid.slice(0, 8), by: { from: a.by.from, sha: a.by.head.slice(0, 8) } };
+        }
+        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 the merge was not covered by a verdict when it happened.` +
+                (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.
@@ -885,7 +1168,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"],
@@ -910,6 +1193,7 @@ const ghFacts = (repo, n) => {
     return {
         state: String(j.state ?? ""),
         mergeable: String(j.mergeable ?? ""),
+        headRefOid: String(j.headRefOid ?? ""),
         checks: j.statusCheckRollup ?? [],
         diff: gh(["pr", "diff", n]),
         citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
@@ -922,7 +1206,15 @@ const ghMerge = (repo, n, method) => {
         stdio: ["ignore", "pipe", "ignore"],
     });
 };
-export async function mergeTool(args, facts = ghFacts, doMerge = ghMerge) {
+const roomLog = (project) => {
+    try {
+        return readFileSync(path.join(ROOT, "rooms", `${project}.jsonl`), "utf8");
+    }
+    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)
@@ -1019,8 +1311,52 @@ 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, unparsed } = verdictsFor(log, n);
+    const gate = gatedAt(verdicts, head, Date.now());
+    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.by.from}. Pass write:true to apply.` };
     doMerge(repo, n, args.method ?? "squash");
     return { ok: true, merged: true, verdict };
 }