agent-coord-mcp 0.26.4 → 0.26.6

package/src/tools/records.ts

@@ -0,0 +1,639 @@
+/*
+ * Record verbs: `next_unblocked` · `claim` · `land`.
+ *
+ * These turn coordinator RECIPES into bus VERBS, so a forgotten step fails closed
+ * instead of looking healthy. The measured cost of the recipe: twelve merges went
+ * 23 hours unlogged, and the queue/DONE loop failed three times in nine hours with
+ * the rule written down each time.
+ *
+ * THE MARKDOWN IS AUTHORITATIVE (ADR-003). These read and write the documents
+ * directly rather than the derived store: a store import is a second source of
+ * truth, and the failure this phase exists to remove is exactly a second source
+ * that drifts.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import {
+  parseWorkDoc,
+  renderWorkDoc,
+  queueItemsOf,
+  doneEntriesOf,
+  type QueueItem,
+  type WorkDoc,
+  phaseCitationsIn,
+  newlyTickedInDiff,
+} from "@davidbalzan/groundwork-seam";
+import { ensureWorktreeTool } from "./worktrees.js";
+import { haltState } from "./stall.js";
+
+const QUEUE_DOC = "docs/QUEUE.md";
+const DONE_DOC = "docs/DONE.md";
+const BOARD_DOC = "docs/WORKSTREAMS.md";
+const PRIORITY_ORDER = { P1: 0, P2: 1, P3: 2 } as const;
+
+const readDoc = (repo: string, rel: string): { text: string; doc: WorkDoc } | null => {
+  const p = path.join(repo, rel);
+  if (!existsSync(p)) return null;
+  const text = readFileSync(p, "utf8");
+  return { text, doc: parseWorkDoc(text) };
+};
+
+/**
+ * Write a document back HUNK-FAITHFULLY: everything the seam did not model is
+ * replayed verbatim, and an UNCHANGED file is not written at all.
+ *
+ * The round trip is byte-exact on all three live documents (measured before this
+ * was built, not assumed). Re-rendering an untouched file would still be a write,
+ * and a write is a diff someone has to review — so the no-op case returns false.
+ */
+function writeDoc(repo: string, rel: string, doc: WorkDoc, original: string): boolean {
+  const out = renderWorkDoc(doc);
+  if (out === original) return false;
+  writeFileSync(path.join(repo, rel), out);
+  return true;
+}
+
+const git = (repo: string, args: string[]): string =>
+  execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+/** `#123` / `owner/repo#123` → "123". */
+function prNumber(pr: string): string | null {
+  const m = /#(\d+)\b/.exec(String(pr)) ?? /^(\d+)$/.exec(String(pr).trim());
+  return m ? (m[1] as string) : null;
+}
+
+// ---------- blocked / no-downstream ----------
+
+const BLOCKED_RE = /\bblocked (?:by|on)\b[:\s]*([^\s·,.;]+)/i;
+
+/** The blocker an item names, if it names one. */
+export function blockedBy(item: QueueItem): string | null {
+  const m = BLOCKED_RE.exec(String(item.text));
+  return m ? (m[1] as string).replace(/[`*]/g, "") : null;
+}
+
+const keyOf = (i: QueueItem) => String(i.text).replace(/\s+/g, " ").slice(0, 60);
+
+/**
+ * A DONE summary a human would have written.
+ *
+ * The first `write:true` run produced
+ * `- [x] Kit: **THE ROOT GATE HAND-LISTS ITS FOUR PACKAGES BY NAME WH — …`:
+ * truncated MID-WORD at 60 characters, leaving an unbalanced `**`. It parses, so
+ * the glyph contract accepts it, and it reads as a line someone abandoned
+ * half-way. Cut on a word boundary and drop emphasis markers rather than leaving
+ * half of one.
+ */
+export function summarize(text: string, max = 96): string {
+  const flat = String(text).replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+  if (flat.length <= max) return flat;
+  const cut = flat.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return `${(at > max * 0.6 ? cut.slice(0, at) : cut).replace(/[\s\-—·,;:]+$/, "")}…`;
+}
+
+/**
+ * Items nothing else waits on.
+ *
+ * "BLOCKS NOTHING" IS NOT "COSTS NOTHING TO DEFER" — and an item that blocks
+ * nothing also ANNOUNCES nothing when it stalls. Everything else surfaces through
+ * the thing waiting on it; these have no such witness, so they go missing silently
+ * and their absence is found by someone re-reading the plan. That is why they are
+ * a SEPARATE AXIS here and not folded into the skipped-because-blocked list: those
+ * are two different states with two different remedies, and one list covering both
+ * leaves the reader to infer which.
+ *
+ * LIMIT, stated because it bounds the claim: dependency is detected from the TEXT.
+ * An unstated dependency is invisible to this, so "no downstream" means "nothing in
+ * the queue SAYS it waits on this", never "nothing waits on this".
+ */
+export function noDownstream(items: QueueItem[]): QueueItem[] {
+  const open = items.filter((i) => !i.done);
+  const named = new Set<string>();
+  for (const i of open) {
+    const b = blockedBy(i);
+    if (b) named.add(b.toLowerCase());
+  }
+  return open.filter((i) => {
+    if (blockedBy(i)) return false; // it waits on something: not this axis
+    const key = keyOf(i).toLowerCase();
+    for (const n of named) if (n.length > 3 && key.includes(n)) return false;
+    return true;
+  });
+}
+
+// ---------- next_unblocked ----------
+
+export const nextUnblockedSchema = { project: z.string().min(1), repo: z.string().optional() };
+
+export async function nextUnblockedTool(args: { project: string; repo?: string }) {
+  // A HALT IS A NAMED STATE AND IT BLOCKS THE LANE, not a suggestion. Handing out
+  // the next item during a board cutover or a cited BLOCKER is how work lands on
+  // a base nobody meant to be building on.
+  const halt = haltState();
+  if (halt.halted) {
+    return {
+      ok: false as const,
+      error: `HALTED by ${halt.by}: ${halt.reason}. No item is handed out while a halt is set — clear it with set_halt{clear:true} when the named condition is gone.`,
+      halted: true,
+    };
+  }
+  const repo = args.repo ?? process.cwd();
+  const q = readDoc(repo, QUEUE_DOC);
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  const items = queueItemsOf(q.doc);
+  const open = items.filter((i) => !i.done);
+  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);
+
+  const skipped: { item: string; blockedBy: string }[] = [];
+  let pick: QueueItem | null = null;
+  for (const { i } of ranked) {
+    const b = blockedBy(i);
+    // NEVER STALL THE LANE waiting on a reorder: a blocked top item is skipped,
+    // visibly, and the next unblocked one is taken.
+    if (b) {
+      skipped.push({ item: keyOf(i), blockedBy: b });
+      continue;
+    }
+    pick = i;
+    break;
+  }
+
+  const silent = noDownstream(open);
+  // AN AXIS THAT FIRES ON EVERYTHING IS NOISE. If no item in the queue declares a
+  // dependency, then "nothing waits on this" is true of every item and the axis
+  // cannot discriminate — listing all of them trains the reader to skim, which is
+  // the severity finding one file over. Say the axis is uninformative instead.
+  const undiscriminating = silent.length === open.length && open.length > 1;
+  return {
+    ok: true as const,
+    project: args.project,
+    open: open.length,
+    next: pick ? { id: pick.id, priority: pick.priority, text: pick.text } : null,
+    skipped,
+    boardHunks: skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
+    // A SEPARATE AXIS, deliberately. See noDownstream().
+    noDownstream: undiscriminating
+      ? {
+          count: silent.length,
+          items: [],
+          why:
+            `NO ITEM IN THIS QUEUE DECLARES A DEPENDENCY, so "nothing waits on this" is true of all ${open.length} and this axis ` +
+            "cannot discriminate. Reporting every item would train you to skim it. Every item's absence here is equally silent, " +
+            "which is a fact about the QUEUE rather than about any item — declare dependencies (`blocked by <id>`) and this becomes useful.",
+        }
+      : {
+          count: silent.length,
+          items: silent.slice(0, 10).map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),
+          why:
+            "nothing in the queue says it waits on these, so their absence is SILENT — they need an explicit check at each stage boundary. " +
+            "Detected from item text: an unstated dependency is invisible here.",
+        },
+  };
+}
+
+// ---------- claim ----------
+
+export const claimSchema = {
+  project: z.string().min(1),
+  agentId: z.string().min(1),
+  itemId: z.string().optional(),
+  repo: z.string().optional(),
+  base: z.string().optional(),
+  task: z.string().optional(),
+};
+
+export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string }) {
+  const halt = haltState();
+  if (halt.halted) {
+    return {
+      ok: false as const,
+      error: `HALTED by ${halt.by}: ${halt.reason}. Claiming is refused while a halt is set.`,
+      halted: true,
+    };
+  }
+  const repo = args.repo ?? process.cwd();
+  const q = readDoc(repo, QUEUE_DOC);
+  if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
+  const items = queueItemsOf(q.doc);
+  let item = args.itemId ? items.find((i) => i.id === args.itemId) : null;
+  if (args.itemId && !item) return { ok: false as const, error: `no queue item with id '${args.itemId}'` };
+  if (!item) {
+    const next = await nextUnblockedTool({ project: args.project, repo });
+    if (!next.ok || !next.next) return { ok: false as const, error: "no unblocked item to claim" };
+    item = items.find((i) => i.id === next.next!.id) ?? null;
+  }
+  if (!item) return { ok: false as const, error: "no unblocked item to claim" };
+
+  // TASK 1 LANDED, SO THE PLACEHOLDER IS GONE RATHER THAN LEFT SWITCHED OFF.
+  //
+  // While `ensure_worktree` did not exist this returned a loud warning that the
+  // worktree was NOT ensured — conditional on the verb's absence, because a
+  // warning that never clears stops being read. The verb exists now, so `claim`
+  // CALLS it: the interface is unchanged and the gap is closed rather than
+  // annotated. An interface with a placeholder nobody removes is how a temporary
+  // state becomes canon.
+  //
+  // 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.
+  const wt = await ensureWorktreeTool({
+    agentId: args.agentId,
+    repo,
+    base: args.base ?? "main",
+    task: args.task,
+  });
+  if (!wt.ok) {
+    return {
+      ok: false as const,
+      error: `cannot claim: no isolated worktree — ${wt.error}`,
+      item: { id: item.id, priority: item.priority },
+    };
+  }
+
+  return {
+    ok: true as const,
+    project: args.project,
+    agentId: args.agentId,
+    item: { id: item.id, priority: item.priority, text: item.text },
+    boardHunk: `| ${keyOf(item)} | ${args.agentId} | \`${wt.branch}\` · ${wt.path} | 🚧 In Progress | — | claimed |`,
+    worktreeEnsured: true,
+    worktree: { path: wt.path, sha: wt.sha, branch: wt.branch, created: wt.created, base: wt.base },
+  };
+}
+
+// ---------- land ----------
+
+export const landSchema = {
+  project: z.string().min(1),
+  pr: z.string().min(1),
+  queueItemId: z.string().optional(),
+  repo: z.string().optional(),
+  base: z.string().optional(),
+  write: z.boolean().optional(),
+};
+
+export async function landTool(args: {
+  project: string;
+  pr: string;
+  queueItemId?: string;
+  repo?: string;
+  base?: string;
+  write?: boolean;
+}) {
+  const repo = args.repo ?? process.cwd();
+  const base = args.base ?? "main";
+  const n = prNumber(args.pr);
+  // A CITED PR OR REFUSE. A `DONE:` without a ref cannot be tied to anything by
+  // anyone, ever — which is its own finding, not a formatting preference.
+  if (!n) {
+    return { ok: false as const, error: `'${args.pr}' names no PR number — a DONE entry with no ref can never be tied to the work. Cite owner/repo#N.` };
+  }
+
+  // MERGED ON THE TARGET'S TIP, NOT THE MERGE BASE.
+  //
+  // "What does the thing I am merging INTO have that I do not?" is answered only
+  // by the target's tip: the merge base is the point the branch DIVERGED from, so
+  // anything landed after the cut is missing from it too — comparing against it is
+  // exactly as blind as comparing against the branch (kit#102/#103). Squash merges
+  // leave no ancestor either, so the citation in the merge SUBJECT is the tie.
+  const ref = `origin/${base}`;
+  let landedIn: string | null = null;
+  let reason: string | null = null;
+  try {
+    const subjects = git(repo, ["log", "-n", "400", "--format=%H %s", ref]);
+    const hit = subjects.split("\n").find((l) => new RegExp(`\\(#${n}\\)|#${n}\\b`).test(l));
+    landedIn = hit ? (hit.split(" ")[0] as string) : null;
+  } catch (e) {
+    reason = `could not read ${ref} (${String((e as Error).message).split("\n")[0]}) — NOT checked, which is not the same as checked and absent`;
+  }
+  if (reason) return { ok: false as const, error: reason };
+  if (!landedIn) {
+    return {
+      ok: false as const,
+      error: `#${n} is not on ${ref} — refusing to record it as landed. Compared against the TARGET TIP (${ref}), not a merge base: an item merged after this branch was cut is missing from the base too.`,
+      comparedAgainst: ref,
+    };
+  }
+
+  const q = readDoc(repo, QUEUE_DOC);
+  const d = readDoc(repo, DONE_DOC);
+  if (!q || !d) return { ok: false as const, error: `need both ${QUEUE_DOC} and ${DONE_DOC} under '${repo}'` };
+
+  const items = queueItemsOf(q.doc);
+
+  // WHICH ITEM A PR CLOSES IS A JUDGEMENT, AND GUESSING IT CLOSED THE WRONG ONE.
+  //
+  // The first real use of this verb matched `#116` against an item that merely
+  // MENTIONED #116 in its body — an item about seam ids — and reported it closed.
+  // With write:true it would have closed unrelated, still-open work. That is the
+  // occurrence-vs-position defect I fixed for sweep tags, reintroduced here in a
+  // different matcher hours later: a citation IN an item's text is not a claim
+  // that the item is closed BY it.
+  //
+  // There is no positional convention to anchor on, so the honest fix is not a
+  // better guess: `land` CLOSES ONLY WHAT IT IS TOLD TO CLOSE. Without an explicit
+  // `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)));
+  const target = args.queueItemId ? items.find((i) => i.id === args.queueItemId) : null;
+  if (args.queueItemId && !target) return { ok: false as const, error: `no queue item with id '${args.queueItemId}'` };
+
+  // CLOSE = STATUS ONLY. The item's priority and body BYTES are untouched: the
+  // seam re-renders `- [x] (P2) <text>` from the same text it parsed, so closing
+  // cannot reword an item. That is asserted by a fixture, not by inspection.
+  let queueChanged = false;
+  if (target) {
+    target.done = true;
+    queueChanged = true;
+  }
+
+  const already = doneEntriesOf(d.doc).some((e) => new RegExp(`#${n}\\b`).test(String(e.ref ?? "")));
+
+  // A DONE LINE A HUMAN WOULD NOT HAVE WRITTEN IS NOT A DONE LINE.
+  //
+  // First real use produced `- [x] PR #117 — #117 · 2026-08-28`: no description of
+  // the work, and a BARE ref where every existing entry carries `owner/repo#N`.
+  // The glyph contract parses it, so a shape check would pass it — and it tells a
+  // reader nothing, which is the whole job of the file.
+  //
+  // So: the summary comes from the item being closed, and a bare `#N` is reported
+  // as UNDER-QUALIFIED rather than silently written.
+  const bareRef = !/[\w.-]+\/[\w.-]+#\d+/.test(String(args.pr));
+  const summary = target ? summarize(target.text) : null;
+
+  const doneLine =
+    already || !summary ? null : `- [x] ${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
+  // DONE.md: it did half the loop, and the half it skipped is the one that failed
+  // three times in nine hours and left twelve merges unlogged for 23 hours. A verb
+  // built to close that gap that does not write DONE is the gap with a tool in
+  // front of it.
+  //
+  // Appended as TEXT to the last done block so the rest of the file is replayed
+  // byte-for-byte: `renderWorkDoc` reproduces every unmodelled line verbatim, and
+  // an entry added to the record model renders through the pinned glyph contract.
+  const wrote: string[] = [];
+  if (args.write) {
+    if (queueChanged && writeDoc(repo, QUEUE_DOC, q.doc, q.text)) wrote.push(QUEUE_DOC);
+    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 as const,
+          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] as { kind: "done"; entries: unknown[] };
+      const parsed = parseWorkDoc(`## Done\n${doneLine}\n`);
+      const entry = doneEntriesOf(parsed)[0];
+      if (!entry) {
+        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)) wrote.push(DONE_DOC);
+    }
+  }
+
+  return {
+    ok: true as const,
+    project: args.project,
+    pr: `#${n}`,
+    comparedAgainst: ref,
+    landedIn: landedIn.slice(0, 8),
+    queueItem: target ? { id: target.id, closed: true, textUnchanged: true } : null,
+    candidates: target
+      ? undefined
+      : candidates.map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),
+    ...(target || !candidates.length
+      ? {}
+      : {
+          note_candidates:
+            `${candidates.length} open item(s) MENTION #${n}; none was closed. A citation in an item's text is not a claim ` +
+            `that the item is closed by it — pass queueItemId to close one deliberately.`,
+        }),
+    doneEntry: doneLine,
+    ...(bareRef
+      ? {
+          refWarning:
+            `'${args.pr}' is an UNDER-QUALIFIED ref — every entry in DONE.md carries owner/repo#N, and a bare #N does not ` +
+            `identify a repository. Pass the full ref; the glyph contract would parse the bare one and it would tell a reader nothing.`,
+        }
+      : {}),
+    ...(summary || already ? {} : { doneEntryWithheld: "no queue item named, so there is no description to write — a DONE line reading only 'PR #N' is not one a human would write" }),
+    alreadyLogged: already,
+    written: wrote,
+    note: args.write ? undefined : "reporting only — pass write:true to apply. The markdown is authoritative; a report is not a write.",
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+ * `merge` — THE MERGE STEP CONSUMES THE CHECK VERDICT, STRUCTURALLY.
+ *
+ * MEASURED COST: kit#123 was merged on a red CI. The wait-loop read `test fail`
+ * and the merge command ran anyway — the instrument RAN, its result was READ,
+ * and the control flow did not DEPEND on it. That is the same shape as the six
+ * shell-pattern mutations that reported clean the same day: a check whose
+ * outcome nothing branches on is decoration, and it trains the reader to skip
+ * it precisely because the outcome afterwards was fine.
+ *
+ * A rule saying "wait for green" cannot fix that, because the failure was not
+ * ignorance of the rule — the coordinator wrote the loop, read the failure, and
+ * merged. So the verdict is not returned for a caller to honour: the merge is
+ * DOWNSTREAM OF IT IN ONE CALL. There is no ordering of this verb in which the
+ * check runs and the merge ignores it.
+ *
+ * Naturally this cannot stop someone typing `gh pr merge`. It removes the
+ * unpoliced step from the path that is meant to be used, and it makes the
+ * bypass a visible choice rather than a loop that looked correct.
+ * ──────────────────────────────────────────────────────────────────────────── */
+
+/** One check as we judge it, normalised across gh's two rollup shapes. */
+export type CheckRow = { name: string; state: string; verdict: "pass" | "fail" | "pending" };
+
+/**
+ * gh reports CheckRun as status+conclusion and StatusContext as a bare state,
+ * and a rollup routinely contains BOTH. Reading only one shape silently scores
+ * the other as unknown — so normalise explicitly and let anything unrecognised
+ * fall to `pending`, which refuses. An unreadable check is not a passing one.
+ */
+export function normalizeChecks(rollup: unknown[]): CheckRow[] {
+  return (rollup ?? []).map((r) => {
+    const c = (r ?? {}) as Record<string, unknown>;
+    const name = String(c.name ?? c.context ?? "(unnamed)");
+    const status = String(c.status ?? "").toUpperCase();
+    const raw = String(c.conclusion ?? c.state ?? "").toUpperCase();
+    if (status && status !== "COMPLETED") return { name, state: status, verdict: "pending" as const };
+    if (raw === "SUCCESS") return { name, state: raw, verdict: "pass" as const };
+    // NEUTRAL and SKIPPED are deliberately NOT passes. A check that declined to
+    // run has not evidenced anything, and scoring it green is the unread-input
+    // defect: reporting clean on something never read.
+    if (raw === "FAILURE" || raw === "ERROR" || raw === "TIMED_OUT" || raw === "CANCELLED" || raw === "ACTION_REQUIRED")
+      return { name, state: raw, verdict: "fail" as const };
+    return { name, state: raw || status || "UNKNOWN", verdict: "pending" as const };
+  });
+}
+
+export const mergeSchema = {
+  project: z.string().min(1),
+  pr: z.string().min(1),
+  repo: z.string().optional(),
+  method: z.enum(["squash", "merge", "rebase"]).optional(),
+  write: z.boolean().optional(),
+};
+
+/** Injected so every refusal branch is provable offline; defaults to real gh. */
+export type PrFacts = {
+  state: string;
+  mergeable: string;
+  checks: unknown[];
+  /** 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"], {
+    cwd: repo,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const j = JSON.parse(out) as Record<string, unknown>;
+  const gh = (args: string[]) => {
+    try {
+      return execFileSync("gh", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      return "";
+    }
+  };
+  // The citation must survive the MERGE, so what counts is what lands in
+  // history: the PR title (which becomes the squash subject) and the commit
+  // subjects. The body is included because a reviewer reads it, but a claim
+  // that lives only in a comment thread is not a record.
+  const meta = JSON.parse(gh(["pr", "view", n, "--json", "title,body,commits"]) || "{}") as Record<string, unknown>;
+  const subjects = ((meta.commits as { messageHeadline?: string }[] | undefined) ?? [])
+    .map((c) => c.messageHeadline ?? "")
+    .join("\n");
+  return {
+    state: String(j.state ?? ""),
+    mergeable: String(j.mergeable ?? ""),
+    checks: (j.statusCheckRollup as unknown[]) ?? [],
+    diff: gh(["pr", "diff", n]),
+    citationText: [String(meta.title ?? ""), subjects, String(meta.body ?? "")].join("\n"),
+  };
+};
+
+/**
+ * The act of merging, injected.
+ *
+ * NOT a testability nicety: with only `facts` injected, a test that supplied
+ * passing checks and `write:true` fell through to the REAL `gh pr merge` and
+ * tried to merge an actual PR. It failed only because that PR was already
+ * merged. A test suite that can merge a live pull request is a worse defect
+ * than anything this verb exists to catch, so the side effect is now something
+ * a caller hands in.
+ */
+export type DoMerge = (repo: string, n: string, method: string) => void;
+const ghMerge: DoMerge = (repo, n, method) => {
+  execFileSync("gh", ["pr", "merge", n, `--${method}`, "--delete-branch"], {
+    cwd: repo,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+};
+
+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,
+) {
+  const repo = args.repo ?? process.cwd();
+  const n = prNumber(args.pr);
+  if (!n) return { ok: false as const, error: `'${args.pr}' names no PR number. Cite owner/repo#N.` };
+
+  let f: PrFacts;
+  try {
+    f = facts(repo, n);
+  } catch (e) {
+    // NOT CHECKED IS NOT CHECKED-AND-GREEN. If we cannot read the verdict we
+    // cannot have consumed it, and this verb's whole claim is that it did.
+    return {
+      ok: false as const,
+      error: `could not read the checks for #${n} (${String((e as Error).message).split("\n")[0]}) — NOT read, which is not the same as read and passing.`,
+    };
+  }
+
+  const checks = normalizeChecks(f.checks);
+  const failed = checks.filter((c) => c.verdict === "fail");
+  const pending = checks.filter((c) => c.verdict === "pending");
+  // EVERY RETURN CARRIES THE POPULATION IT JUDGED. "All passed" over an empty
+  // set is the sentence this verb exists to make unsayable.
+  const verdict = { population: checks.length, checks, failed: failed.map((c) => c.name), pending: pending.map((c) => c.name) };
+
+  if (f.state !== "OPEN") return { ok: false as const, error: `#${n} is ${f.state || "not OPEN"} — nothing to merge.`, verdict };
+
+  // NO CHECKS IS NOT PASSING CHECKS.
+  //
+  // Same invariant as the stall clock: no alerts is not no stalls, and a clock
+  // that stopped reads quiet exactly like a system that is fine. An empty
+  // rollup is the strongest-looking green there is — zero failures — and it is
+  // evidence of nothing at all.
+  if (checks.length === 0)
+    return { ok: false as const, error: `#${n} reports ZERO checks. No checks is not passing checks — an empty rollup has zero failures and evidences nothing.`, verdict };
+
+  if (failed.length)
+    return { ok: false as const, error: `#${n} has ${failed.length} of ${checks.length} check(s) FAILING: ${failed.map((c) => c.name).join(", ")}. Refusing to merge.`, verdict };
+
+  if (pending.length)
+    return { ok: false as const, error: `#${n} has ${pending.length} of ${checks.length} check(s) not yet terminal: ${pending.map((c) => c.name).join(", ")}. A check still running has not returned a verdict to consume.`, verdict };
+
+  // EVERY NEWLY-TICKED CHECKBOX MUST BE CITED, CHECKED AT THE MERGE.
+  //
+  // Twice in one day a PR carried two things and left one unrecorded: kit#126
+  // ticked 4.4 and named it nowhere, and all five of Task 5's boxes shipped
+  // inside kit#127 alongside a CI fix. The pattern is not carelessness — a PR
+  // that fixes an incident AND delivers planned work gets the incident
+  // remembered and the work forgotten, because the incident is what everyone
+  // is talking about. Review caught neither; the coordinator found both after
+  // the fact.
+  //
+  // So it is checked where the record is actually made. `doctor`'s
+  // `phase-checkbox` finds this too, but only AFTER the merge, against DONE.md
+  // and merged subjects — by which time the claim is already in history
+  // unevidenced. The citation grammar is shared through seam rather than
+  // copied, because a copied grammar is two grammars the moment one is fixed.
+  const ticked = newlyTickedInDiff(f.diff ?? "");
+  if (ticked.size) {
+    const cited = phaseCitationsIn(f.citationText ?? "");
+    const uncited = [...ticked].filter((k) => !cited.has(k));
+    if (uncited.length) {
+      const names = uncited.map((k) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; });
+      return {
+        ok: false as const,
+        error:
+          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNCITED: ${names.join(", ")}. ` +
+          `Once this merges, the tick claims progress that nothing in history evidences. Name them in the PR title or a commit subject (e.g. "${names[0]}") — the subject is what survives a squash merge.`,
+        verdict,
+        uncited: names,
+      };
+    }
+  }
+
+  if (f.mergeable === "CONFLICTING")
+    return { ok: false as const, error: `#${n} is CONFLICTING with its base.`, verdict };
+
+  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.` };
+
+  doMerge(repo, n, args.method ?? "squash");
+  return { ok: true as const, merged: true as const, verdict };
+}

package/src/tools/registry.ts

@@ -1,4 +1,5 @@
 import { detachAgentTool } from "./transport.js";
+import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -60,6 +61,7 @@ import {
   type Cursor,
   type Source,
   type TransportMarker,
+  roomFeedOf,
   sourceFile,
   getOffset,
   setOffset,
@@ -123,6 +125,13 @@ export async function registerTool(args: { agentId: string; project?: string; ro
   const roleUpdate = resolveRoleUpdate(args.agentId, before[args.agentId], args.role);
   if (!roleUpdate.ok) return { ok: false as const, error: roleUpdate.error };
 
+  // 4.2 — a SECOND coordinator may not register while the first is away.
+  // Checked on the RESOLVED role, not the string the caller passed: the refusal
+  // has to see what the registry will actually record, or a spelling slips past
+  // the guard and lands as `coordinator` anyway.
+  const second = secondCoordinatorRefusal(readAway(), args.agentId, roleUpdate.roleId);
+  if (second) return { ok: false as const, error: second };
+
   const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     const now = Date.now();
     const existing = current[args.agentId];
@@ -300,7 +309,19 @@ export async function listAgentsTool() {
       ...heartbeatFields,
       capabilities: merged.length > 0 ? merged : undefined,
       transport: transport
-        ? { kind: transport.transport, tmuxTarget: transport.tmuxTarget, pid: transport.pid }
+        ? {
+            kind: transport.transport,
+            tmuxTarget: transport.tmuxTarget,
+            pid: transport.pid,
+            // `attached` alone said nothing about WHAT is attached. A pusher
+            // started `--no-room` delivers DMs only, and its marker used to be
+            // indistinguishable from a full one — so an agent could sit with
+            // its room feed off while status read healthy (worker-2).
+            //
+            // Absent is UNKNOWN, never "on": an older pusher's marker cannot
+            // answer, and answering for it is how the original defect worked.
+            rooms: roomFeedOf(transport),
+          }
         : undefined,
     };
   });