agent-coord-mcp 0.26.18 → 0.26.20

package/hooks/tmux-pusher.mjs

@@ -288,7 +288,11 @@ function readJsonl(file) {
 // Allowlisted control commands the bus may type into this CLI. Mirrors
 // CONTROL_COMMANDS in src/tools/transport.ts and scripts/coord-pusher.mjs
 // (test/allowlist-parity.test.mjs locks the three); kept tiny + literal so a bugged/compromised
-// sender can't smuggle an arbitrary slash command past the guard below.
+// sender can't smuggle an arbitrary slash command onto the RAW submit path.
+// ⚠ THIS SET IS THE GATE. It used to be backed by a second check that dropped any
+// text starting with "/"; that check was removed in ⟨q-f14692ca⟩ because it silently
+// discarded legitimate messages and never saw the multi-line shape it was aimed at.
+// Membership here, plus bracketed paste on the peer path, is now the whole defence.
 const CONTROL_COMMANDS = new Set(["/clear", "/compact", "/reload-skills"]);
 
 // Shells we refuse to inject into: if the pane's foreground command is one of
@@ -321,9 +325,35 @@ function isControl(m) {
 function shouldInject(m) {
   if (!m || m.from === AGENT_ID) return false;
   if (ALLOWLIST.length > 0 && !ALLOWLIST.includes(m.from)) return false;
-  // Authorized control command — bypass the slash guard, injected raw later.
+  // Authorized control command — injected RAW later, so the allowlist in
+  // `isControl` is the gate that matters. Checked first and unchanged.
   if (isControl(m)) return true;
-  if (typeof m.text === "string" && m.text.trimStart().startsWith("/")) return false;
+
+  // ⛔ THE SLASH DROP USED TO LIVE HERE AND IT IS GONE ON PURPOSE (⟨q-f14692ca⟩).
+  //
+  // It returned false for any text starting with "/", which SILENTLY discarded
+  // the message: the sender was told nothing, and `collectSource` advances the
+  // offset past rejected lines, so it was never retried either. Measured in an
+  // isolated pane: a plain message and a trailing message both arrived, the
+  // slash-leading one between them did not, and the pusher log said nothing.
+  //
+  // AND IT WAS PROTECTING NOTHING THAT IS NOT ALREADY PROTECTED TWICE, measured
+  // rather than reasoned:
+  //   1. `formatBatch` prefixes every peer line with `  [DM hh:mm from] `, so a
+  //      single-line "/foo" reaches the pane with ZERO lines starting with "/" —
+  //      it is chat text, not a command.
+  //   2. Ordinary batches paste with `bracketed = true`, which makes the whole
+  //      payload inert: embedded newlines cannot submit a line or smuggle a
+  //      "/command". That is the defence that actually covers the multi-line
+  //      case, which this check never caught — `trimStart()` only ever examined
+  //      the FIRST line, so "opener\n/clear" passed straight through it.
+  //
+  // So the old guard was wrong in both directions at once: it dropped safe
+  // single-line messages, and it did not see the multi-line shape it was aimed
+  // at. Removing it restores delivery; the protection that matters is the
+  // allowlist above plus bracketed paste, and BOTH are pinned by tests in
+  // test/slash-message-delivery.test.mjs. ⚠ If anyone makes the peer path paste
+  // raw, those tests fail — which is the price of not having this check.
   return true;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.18",
+  "version": "0.26.20",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {

package/src/capabilities.ts

@@ -39,6 +39,14 @@ import { suggestRecordType, typedRecordMode } from "./typed-records.js";
 import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
 import { recordAuthorityFor } from "./roles.js";
 import { subscriptionHealth } from "./tools/events.js";
+import {
+  configuredTransport,
+  runningTransport,
+  isTmuxKind,
+  targetOf,
+  type TransportKind,
+} from "./transports/index.js";
+import { readAllTransportMarkers } from "./tools/registry.js";
 
 export type ProbeResult = {
   id: string;
@@ -129,6 +137,44 @@ const PROBES: Probe[] = [
   },
 ];
 
+/**
+ * TWO CLAIMS, AND THE TYPE MAKES YOU CARRY BOTH (Phase 5.4 Task 3.3).
+ *
+ * *A config value is a label someone typed.* `configured` is that label;
+ * `running` is answered by CALLING the transport in this process. They are
+ * separate fields because they are separate facts, and `agrees` exists so a
+ * reader cannot skim one and believe the other.
+ *
+ * ⛔ THIS IS THE MACHINE-READABLE FORM OF A MISTAKE MADE IN PROSE. An hour
+ * before this shipped, a Task 2 contract asserted that "every seat in this fleet
+ * is running on the code you are refactoring." Measured afterwards: every server
+ * and every pusher loads the global install at 0.26.19 while `main` declared
+ * 0.26.20 — the fleet was running PRE-refactor code and always had been. The
+ * claim came from what the repo said, not from what any process answered. That
+ * is `configured` reported as `running`, in English instead of in a type.
+ *
+ * `running` is `undefined` when nothing is wired, which is NOT "tmux by
+ * default": a process with no transport delivers nothing, and substituting a
+ * default there would restage the same substitution one layer down.
+ */
+export type TransportCapability = {
+  configured: TransportKind;
+  /** Answered by calling the transport, never by reading config. */
+  running: TransportKind | undefined;
+  agrees: boolean;
+  /** What was called and what came back. */
+  evidence: string;
+  /** Where `configured` came from — config file, env, or the built-in default. */
+  configuredSource: "config" | "env" | "default";
+  /**
+   * MIXED FLEET, MADE LOUD (3.4). Agents whose marker names a transport other
+   * than the running one. Whole-fleet is the rule; this is the code noticing
+   * when reality disagrees with the rule rather than trusting it — at 2-of-5
+   * stall coverage a silent disagreement is a failure nobody can see.
+   */
+  disagreeingAgents: { agentId: string; marker: string }[];
+};
+
 export type CapabilityReport = {
   /**
    * WHICH PROCESS ANSWERED. Not evidence of anything — context, so a reader can
@@ -140,6 +186,8 @@ export type CapabilityReport = {
   probes: ProbeResult[];
   missing: string[];
   ok: boolean;
+  /** Absent only if the probe itself threw — see `probeTransport`. */
+  transport?: TransportCapability;
   note: string;
 };
 
@@ -182,7 +230,62 @@ import { resolveServerIdentity } from "./server-identity.js";
 
 export const capabilitiesSchema = {} as const;
 
+/**
+ * Build the transport capability by CALLING things, then compare.
+ *
+ * Deliberately async and deliberately separate from `probeCapabilities`, which
+ * is synchronous: the transport answer requires I/O (a `tmux -V`, a pane probe),
+ * and making the sync report do I/O to obtain it would have meant reading the
+ * config instead — which is the substitution this whole field exists to refuse.
+ */
+export async function probeTransport(): Promise<TransportCapability> {
+  const conf = configuredTransport();
+  const running = await runningTransport();
+
+  // 3.4 — a mixed fleet must be detectable and LOUD. Every marker on disk is
+  // read and any that names a different transport is listed by agent, because a
+  // count alone tells you something is wrong and not where to look.
+  const disagreeingAgents: { agentId: string; marker: string }[] = [];
+  try {
+    // READ-ONLY on purpose. The reaping loader would delete markers it judged
+    // not-live, so a diagnostic would mutate the fleet it is describing — and it
+    // would hide the remote kind, whose liveness needs a registry heartbeat.
+    for (const { marker, live } of await readAllTransportMarkers()) {
+      if (running.kind !== undefined && marker.transport !== running.kind) {
+        const where = isTmuxKind(marker.transport) ? targetOf(marker) : undefined;
+        disagreeingAgents.push({
+          agentId: marker.agentId,
+          marker: `${marker.transport}${where ? ` (${where})` : ""}${live ? "" : " [stale]"}`,
+        });
+      }
+    }
+  } catch {
+    // An unreadable transports dir is not evidence of a uniform fleet. Left
+    // empty, and the caller can see `running` was still answered.
+  }
+
+  return {
+    configured: conf.kind,
+    running: running.kind,
+    agrees: running.kind === conf.kind,
+    evidence: running.evidence,
+    configuredSource: conf.source,
+    disagreeingAgents,
+  };
+}
+
 export async function capabilitiesTool() {
   const id = resolveServerIdentity();
-  return probeCapabilities({ module: id.path, versionLabel: id.version });
+  const report = probeCapabilities({ module: id.path, versionLabel: id.version });
+  try {
+    return { ...report, transport: await probeTransport() };
+  } catch (e) {
+    // A THROWN TRANSPORT PROBE IS NOT A BROKEN VERB. An unknown configured value
+    // refuses at startup by design, and this verb is exactly what an operator
+    // reaches for to find out why — so it must still answer, and say what threw.
+    return {
+      ...report,
+      transportError: `transport probe threw: ${(e as Error).message}`,
+    };
+  }
 }

package/src/server.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { randomUUID } from "node:crypto";
+import { initTransportFromConfig } from "./transports/index.js";
 import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -96,6 +97,8 @@ import {
   ensureWorktreeTool,
   refreshWorktreesSchema,
   refreshWorktreesTool,
+  releaseWorktreeSchema,
+  releaseWorktreeTool,
   claimSchema,
   claimTool,
   landSchema,
@@ -659,6 +662,12 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     refreshWorktreesSchema,
     gate(null, refreshWorktreesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
+  addTool(
+    "release_worktree",
+    "GIVE A WORKTREE BACK — the counterpart to ensure_worktree, which created trees while nothing released them, leaving `git worktree remove`/`prune` as a hand step in five role cards. Identify the tree by `agentId` or `path`. REFUSES the primary checkout (the path everyone already has); REFUSES a DIRTY tree with no override, because uncommitted work is what a diff cannot show and git cannot give back; and REFUSES a tree whose commits cannot be shown to have landed. Landedness is decided by PATCH ID, never ancestry — under squash merge a landed branch's shas never enter the base, so ancestry calls every finished tree mid-slice forever and would refuse exactly the trees that are safe to release. A patch-id negative is INCONCLUSIVE rather than a no, so it refuses and says so; `force:true` releases anyway and is recorded in the result. Removing and pruning are ONE act here, not two lines of prose the caller remembers. Reports by default; pass apply:true to remove.",
+    releaseWorktreeSchema,
+    gate(null, releaseWorktreeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
 
   addTool(
     "next_unblocked",
@@ -669,7 +678,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "claim",
-    "Bind a queue item to an agent and produce the 🚧 board row. With no itemId it takes next_unblocked. WARNS LOUDLY while `ensure_worktree` (Phase 5 Task 1) does not exist: the claim binds the item and the row only, and creating an isolated worktree at origin/<base> is still yours. The warning is conditional on that verb's absence, so it stops once Task 1 lands.",
+    "Bind a queue item to an agent, ENSURE THE AGENT HAS AN ISOLATED WORKTREE, and produce the \ud83d\udea7 board row. With no itemId it takes next_unblocked. `claim` CALLS `ensure_worktree` rather than telling you to — a worktree that cannot be ensured is a REFUSAL, not a warning, because binding an item to an agent with nowhere isolated to work is the shared-checkout failure this pair exists to prevent. A REUSED tree that is not at origin/<base> is also refused, naming how far behind it is and pointing at `refresh_worktrees`: `claim` means START SOMETHING NEW, and a tree left on last week's base produces confidently-wrong work with nothing about the result looking stale. A freshly created tree is cut from origin/<base> and needs no such check. Returns `worktreeEnsured` with the tree's path and branch, and writes the board cell as the REMOTE-TRACKING ref so the same row reads identically from every checkout.",
     claimSchema,
     gate(null, claimTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -799,6 +808,26 @@ async function main() {
   loadTokenMap(true);
   process.on("SIGHUP", () => loadTokenMap(false));
 
+  // TRANSPORT, RESOLVED ONCE, BEFORE ANYTHING CAN ATTACH (Phase 5.4 Task 3.1).
+  //
+  // Here rather than lazily on first use, because an unknown value must REFUSE
+  // AT STARTUP: a refusal at first-attach would leave a server that came up
+  // healthy and fails one agent, which looks like that agent's problem. It also
+  // fixes the value for the process lifetime — whole-fleet, no per-seat
+  // branching in send_command or attach.
+  try {
+    const t = initTransportFromConfig();
+    if (t.source !== "default") {
+      console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
+    }
+  } catch (e) {
+    // Loud, and fatal. A server that starts with an unusable transport config
+    // delivers nothing while reporting itself up, and a quiet transport is the
+    // one failure this fleet cannot distinguish from working.
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+
   // Transport selector. AGENT_COORD_HTTP_PORT set → run as a long-lived HTTP
   // daemon (Streamable HTTP transport + bearer-token auth). Otherwise the
   // historical stdio behavior (per-client subprocess spawned by Claude Code).

package/src/tools/records.ts

@@ -70,10 +70,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 +226,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 +319,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);
   });
 }
@@ -296,6 +390,9 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   const q = readDoc(repo, QUEUE_DOC);
   if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
   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 +410,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);
@@ -390,6 +536,26 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     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 +572,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
@@ -789,9 +961,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,8 +993,18 @@ 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.