agent-coord-mcp 0.26.19 → 0.26.21

package/src/tools/records.ts

@@ -15,6 +15,8 @@ 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,
   renderWorkDoc,
@@ -34,6 +36,8 @@ import {
   type DoneEntry,
 } 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, type RecordEvent } from "./events.js";
@@ -70,10 +74,85 @@ const readDoc = (repo: string, rel: string): { text: string; doc: WorkDoc } | nu
  * 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: string, rel: string, doc: WorkDoc, original: string): { written: boolean; stamped: string[] } {
+/**
+ * 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 {
+  constructor(
+    readonly rel: string,
+    readonly detail: string,
+    readonly alreadyWritten: string[],
+  ) {
+    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.name = "StaleWriteError";
+  }
+}
+
+/** What moved, in terms a caller can act on without diffing the file itself. */
+function describeDrift(original: string, current: string): string {
+  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: string,
+  rel: string,
+  doc: WorkDoc,
+  original: string,
+  alreadyWritten: string[] = [],
+): { written: boolean; stamped: string[] } {
   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 };
 }
 
@@ -151,6 +230,15 @@ export function summarize(text: string, max = 96): string {
  * the queue SAYS it waits on this", never "nothing waits on this".
  */
 export function noDownstream(items: QueueItem[]): QueueItem[] {
+  // ⚠ 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<string>();
   for (const i of open) {
@@ -235,43 +323,53 @@ function boardHoldsItem(rows: WorkstreamsV1Row[], id: string, text: string): boo
  * 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.
+ *
+ * ⚠ 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.
  *
- * 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:
+ * ✅ 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.
  *
- *   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.
+ * ⚠ 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.
  *
- * 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.
+ * ⛔ 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: DoneEntry[], id: string, text: string): boolean {
   const norm = (v: string) => 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);
   });
 }
@@ -293,9 +391,19 @@ 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.
+  const parsedOpen = items.filter((i) => !i.done).length;
 
   // ALREADY-DELIVERED ITEMS ARE NEVER RE-OFFERED, and `!i.done` alone does not
   // establish that.
@@ -313,17 +421,66 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // (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<string>();
+  // ⛔⛆ `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<string, "board" | "done">();
   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<string, number>();
+  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);
@@ -387,9 +544,33 @@ 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,
+    // ⛔ 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
@@ -406,6 +587,12 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
       ...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
@@ -650,7 +837,29 @@ 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 MergeFacts = { headRefOid: string; mergedAt: string } | 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"], {
+      cwd: repo,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const j = JSON.parse(out) as { headRefOid?: string; mergedAt?: string };
+    if (!j.headRefOid || !j.mergedAt) return null;
+    return { headRefOid: String(j.headRefOid), mergedAt: String(j.mergedAt) };
+  } catch {
+    return null;
+  }
+};
+
+export async function landTool(
+  args: {
   project: string;
   pr: string;
   queueItemId?: string;
@@ -658,7 +867,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);
@@ -773,8 +985,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.
   //
@@ -789,9 +1034,14 @@ export async function landTool(args: {
   // an entry added to the record model renders through the pinned glyph contract.
   const wrote: string[] = [];
   let stampedNotSupplied: string[] = [];
+  // 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);
+      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
@@ -816,9 +1066,19 @@ export async function landTool(args: {
         return { ok: false as const, 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).written) wrote.push(DONE_DOC);
+      if (writeDoc(repo, DONE_DOC, d.doc, d.text, wrote).written) wrote.push(DONE_DOC);
     }
   }
+  } catch (e) {
+    if (e instanceof StaleWriteError) {
+      return {
+        ok: false as const,
+        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.
   //
@@ -847,12 +1107,53 @@ 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, unparsed } = verdictsFor(log, n);
+    const a = gatedAt(verdicts, mf.headRefOid, at);
+    if (a.gated) {
+      return { checked: true as const, gated: true as const, head: mf.headRefOid.slice(0, 8), by: { from: a.by.from, sha: a.by.head.slice(0, 8) } };
+    }
+    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 the merge was not covered by a verdict when it happened.` +
+        (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.
@@ -964,13 +1265,15 @@ 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;
 };
 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"],
@@ -994,6 +1297,7 @@ const ghFacts = (repo: string, n: string): PrFacts => {
   return {
     state: String(j.state ?? ""),
     mergeable: String(j.mergeable ?? ""),
+    headRefOid: String(j.headRefOid ?? ""),
     checks: (j.statusCheckRollup as unknown[]) ?? [],
     diff: gh(["pr", "diff", n]),
     citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
@@ -1019,10 +1323,28 @@ 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;
+const roomLog: ReadVerdictLog = (project) => {
+  try {
+    return readFileSync(path.join(ROOT, "rooms", `${project}.jsonl`), "utf8");
+  } 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);
@@ -1131,8 +1453,55 @@ 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, 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 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.by.from}. Pass write:true to apply.` };
 
   doMerge(repo, n, args.method ?? "squash");
   return { ok: true as const, merged: true as const, verdict };