agent-coord-mcp 0.26.17 → 0.26.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.17",
+  "version": "0.26.18",
   "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/server.ts

@@ -627,7 +627,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "stall_check",
-    "The stall predicate over the board and the bus: a 🚧 row whose agent's heartbeat is older than the window, or whose claimed branch has no commits in it. HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.",
+    "The stall predicate over the board and the bus: a 🚧 In Progress or 🔍 In Review row (both are lanes somebody is working; a review that never gets re-gated is the stall shape of a QA-gated fleet) whose agent's heartbeat is older than the window, or whose claimed branch has no commits in it. HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.",
     stallCheckSchema,
     gate(null, stallCheckTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -662,7 +662,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "next_unblocked",
-    "The next queue item a WORKER can claim: re-reads docs/QUEUE.md via the seam, orders P1>P2>P3 with document order breaking ties, and SKIPS a blocked item rather than stalling the lane on a reorder (returning the board hunk to record the skip). Also skips — as its own reported axis, `notClaimable`, never silently — canon prose (`[SWEEP:canon]`/`[SWEEP:canon.N]`) that the aide/coordinator author directly and no worker takes as code work. Also reports items NOTHING WAITS ON as their own axis: an item that blocks nothing announces nothing when it stalls, so its absence is silent and needs an explicit check at a stage boundary.",
+    "The next queue item a WORKER can claim: re-reads docs/QUEUE.md via the seam, orders P1>P2>P3 with document order breaking ties, and SKIPS a blocked item rather than stalling the lane on a reorder (returning the board hunk to record the skip). Also skips — as its own reported axis, `notClaimable`, never silently — canon prose (`[SWEEP:canon]`/`[SWEEP:canon.N]`) that the aide/coordinator author directly and no worker takes as code work. Also skips — as its own axis, `awaitingDecision`, never silently — an item that DECLARES it awaits a named human (`**[AWAITS:<who>]**` leading the item line; never inferred from prose): dependency-free and unbuildable at once, so it is reported for the human and not routed to a lane. Also reports items NOTHING WAITS ON as their own axis: an item that blocks nothing announces nothing when it stalls, so its absence is silent and needs an explicit check at a stage boundary.",
     nextUnblockedSchema,
     gate(null, nextUnblockedTool as (a: Record<string, unknown>) => Promise<unknown>),
   );

package/src/tools/admin.ts

@@ -31,6 +31,7 @@ import {
   type Message,
   type StatusEntry,
   isDecision,
+  agentIdFromCursorFilename,
 } from "./shared.js";
 
 // ---------- prune ----------
@@ -73,7 +74,13 @@ export async function adjustCursors(removals: {
   const perAgentInboxRemoved = removals.perAgentInboxRemoved ?? {};
   const cursorsAdjusted: string[] = [];
   for (const cname of await listCursorFiles()) {
-    const id = cname.replace(/\.json$/, "");
+    // q-40449919: this was `cname.replace(/\.json$/, "")`, which strips only
+    // the outer extension. A push cursor's `<agent>.push.json` then keyed
+    // `perAgentInboxRemoved` lookups below on `<agent>.push` — a key that
+    // never matches — so a push cursor's inboxOffset was silently never
+    // decremented after a prune shrank the inbox, drifting it toward a
+    // false past-EOF the next time doctor ran.
+    const { id } = agentIdFromCursorFilename(cname);
     const cursorPath = path.join(CURSOR_DIR, cname);
     let touched = false;
     await updateJson<Cursor>(cursorPath, {}, (current) => {

package/src/tools/away.ts

@@ -155,7 +155,14 @@ export function secondCoordinatorRefusal(
 
 export const coordAwaySchema = {
   project: z.string().min(1),
-  on: z.boolean(),
+  // Omitted → a QUERY: report current state and mutate nothing (q-1abbbdbf).
+  // `/coord-away` used to be a bare toggle read by a human deciding which
+  // direction to call it — the incident this fixes is David typing it
+  // meaning ARM while it was already armed, and the aide independently
+  // reading the same typed command as RELEASE, with no state visible to
+  // either of them before acting. State-it-aloud-first only works if there
+  // is a state to read that does not itself flip the switch.
+  on: z.boolean().optional(),
   /** The agent leading in David's absence — the aide. */
   leadId: z.string().optional(),
   /** Repo-relative path where decisions taken during the absence are written. */
@@ -184,7 +191,7 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
 
 export async function coordAwayTool(args: {
   project: string;
-  on: boolean;
+  on?: boolean;
   leadId?: string;
   decisionLog?: string;
   until?: string;
@@ -195,6 +202,38 @@ export async function coordAwayTool(args: {
   const state = readAway();
   const prior = state[args.project];
 
+  // QUERY — `on` omitted. Reads, never writes: no coverage measurement, no
+  // refusal, no side effect. This is the call a card makes to state current
+  // status aloud BEFORE deciding which direction to arm/release, so the
+  // decision is never made blind the way it was on 2026-08-30/31.
+  if (args.on === undefined) {
+    if (!prior?.on) {
+      return {
+        ok: true as const,
+        query: true as const,
+        project: args.project,
+        armed: false,
+        state: prior ?? null,
+        summary: prior
+          ? `'${args.project}' is NOT armed — last released ${prior.at}.`
+          : `'${args.project}' is NOT armed — never armed.`,
+      };
+    }
+    return {
+      ok: true as const,
+      query: true as const,
+      project: args.project,
+      armed: true,
+      state: prior,
+      summary:
+        `'${args.project}' is ARMED — '${prior.leadId}' leads since ${prior.at}` +
+        `${prior.until ? ` until ${prior.until}` : ""}. ` +
+        `Coverage ${prior.coverage.measurable}/${prior.coverage.checked}` +
+        `${prior.blindAcknowledged ? " (ACKNOWLEDGED BLIND)" : ""}. ` +
+        `Decisions logged to ${prior.decisionLog}.`,
+    };
+  }
+
   if (args.on) {
     // A LEAD WITH NO NAME IS AN ABSENCE DESCRIBED AS COVERED, which is strictly
     // worse than an absence everyone can see is uncovered.
@@ -261,8 +300,12 @@ export async function coordAwayTool(args: {
       state: state[args.project],
       refused: LEAD_REFUSED,
       parked: PARKED_CATEGORIES,
+      // A confirmation naming the transition, not just the imperative
+      // direction (q-1abbbdbf) — "ON" and "already ON" read the same at a
+      // glance; "OFF → ARMED" cannot be misread as a no-op or a repeat.
+      transition: "OFF → ARMED" as const,
       announce:
-        `AGENT_ACTION: coord-away ON — David is away${args.until ? ` until ${args.until}` : ""}; '${args.leadId}' LEADS. ` +
+        `OFF → ARMED. AGENT_ACTION: coord-away ON — David is away${args.until ? ` until ${args.until}` : ""}; '${args.leadId}' LEADS. ` +
         `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
         `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
         `Decisions logged to ${args.decisionLog}. ` +
@@ -280,8 +323,9 @@ export async function coordAwayTool(args: {
   return {
     ok: true as const,
     state: state[args.project],
+    transition: "ARMED → RELEASED" as const,
     announce:
-      `AGENT_ACTION: coord-away RELEASED on '${args.project}' — David is back; '${prior.leadId}' stands down as lead. ` +
+      `ARMED → RELEASED. AGENT_ACTION: coord-away RELEASED on '${args.project}' — David is back; '${prior.leadId}' stands down as lead. ` +
       `Anything parked during the absence is still parked: release does not authorise it. Decisions taken: ${prior.decisionLog}.`,
   };
 }

package/src/tools/records.ts

@@ -18,6 +18,7 @@ import { z } from "zod";
 import {
   parseWorkDoc,
   renderWorkDoc,
+  renderWorkDocForWrite,
   queueItemsOf,
   doneEntriesOf,
   type QueueItem,
@@ -25,10 +26,16 @@ import {
   phaseCitationsDetailed,
   newlyTickedInDiff,
   sweepTagOf,
+  awaitingOf,
+  refsIn,
+  refsMatch,
+  workstreamsV1RowsOf,
+  type WorkstreamsV1Row,
+  type DoneEntry,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
-import { haltState } from "./stall.js";
+import { haltState, isInFlightStatus } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
@@ -51,11 +58,23 @@ const readDoc = (repo: string, rel: string): { text: string; doc: WorkDoc } | nu
  * 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;
+/**
+ * EVERY SUPPORTED WRITE OF A WORK DOC GOES THROUGH HERE, and it stamps.
+ *
+ * `renderWorkDocForWrite` records identity for any queue item that lacks it,
+ * including rows this caller did not author (q-c50e9b83) — the absorbed raw
+ * append is exactly the case, and stamping only the caller's own rows would keep
+ * the defect and move the blame. Every id written is the one the item already
+ * has, so nothing changes value.
+ *
+ * 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[] } {
+  const { text, stamped } = renderWorkDocForWrite(doc);
+  if (text === original) return { written: false, stamped: [] };
+  writeFileSync(path.join(repo, rel), text);
+  return { written: true, stamped };
 }
 
 const git = (repo: string, args: string[]): string =>
@@ -67,6 +86,25 @@ function prNumber(pr: string): string | null {
   return m ? (m[1] as string) : null;
 }
 
+/**
+ * The `owner/repo` a BARE `#N` in this repo's docs should be read as naming —
+ * the same derivation `groundwork doctor` makes (`originRepoOf`) before it ties
+ * a closed item's citation to DONE.md. `land` must decide "already cited" with
+ * the SAME rule the auditor will apply, or the two disagree again one level
+ * down: a bare `#77` in an item body is a tie for doctor only when the origin
+ * URL says which repo, and it is a tie here under exactly that condition.
+ * Null (no remote, not a repo) means an unknown context, never a guessed one.
+ */
+function originRepoOf(repo: string): string | null {
+  try {
+    const url = git(repo, ["remote", "get-url", "origin"]);
+    const m = /[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(url);
+    return m ? (m[1] as string) : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------- blocked / no-downstream ----------
 
 const BLOCKED_RE = /\bblocked (?:by|on)\b[:\s]*([^\s·,.;]+)/i;
@@ -127,6 +165,117 @@ export function noDownstream(items: QueueItem[]): QueueItem[] {
   });
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+ * DELIVERED — READ THE RECORD'S STRUCTURE, NOT A SUBSTRING OF THE FILE.
+ *
+ * This was `doneText.includes(id) || boardText.includes(id)` over two whole
+ * documents, so ANY MENTION ANYWHERE counted as "handed out" — including a row
+ * written specifically to warn that an item must NOT be built (q-2ba7f0c5).
+ * The inversion is the finding: the more carefully a coordinator documents why
+ * something must not be routed, the more completely it disappears from the verb
+ * that routes.
+ *
+ * MEASURED ON `origin/main` @17b72ff, and the numbers moved the fix twice:
+ *
+ *   q-11257590  hidden by the AIDE'S OWN `🚧 In Progress` ROW, which merely
+ *               MENTIONS it in its Last note. A status-only rule leaves it
+ *               hidden — the occurrence-vs-position defect one level in — so
+ *               identification has to be the row's SUBJECT, not any of its cells.
+ *   q-ad0fc8d4  hidden by its own `⏸ Returned to the aide unbuilt` row.
+ *   q-507e80c4  hidden with NO PARSED ROW AT ALL: the id sits in board prose
+ *               outside the table, which a whole-file substring test cannot
+ *               distinguish from a lane.
+ *   q-507e80c4  ALSO hidden by a DONE entry that CITES it as the still-open
+ *               part (b) of work whose part (a) landed — the canon case
+ *               q-912a67e8 requires, LIVE today rather than latent.
+ *
+ * Neither half is fixed by relabelling a row: that is satisfying a guard by
+ * editing what it reads (q-507e80c4 constraint 1) and it would destroy the
+ * warning the row exists to give.
+ */
+
+/** The ids a board row names as ITS OWN SUBJECT — the Stream cell only. */
+function rowSubjectIds(row: WorkstreamsV1Row): string[] {
+  return [...String(row.stream).matchAll(/\b(q-[0-9a-f]{8})\b/g)].map((m) => m[1] as string);
+}
+
+/**
+ * Does the board show this item as IN SOMEBODY'S HANDS?
+ *
+ * Two conditions, and both are needed — measured, not reasoned:
+ *   STATUS  the row is in flight (`isInFlightStatus`, shared with `stall_check`
+ *           since #219 rather than a second glyph list). `⏸ Parked`,
+ *           `⏸ Returned`, `⏳ Queued`, `⛔ Blocked`, `🚫 Unstaffable`,
+ *           `🔻 Orphaned` describe work nobody holds, so they do not silence.
+ *   SUBJECT the row's Stream cell names the item — by recorded id, or by the
+ *           text prefix `claim` has always written there. A mention in a Last
+ *           note is one lane REFERRING to another item — the aide's live row
+ *           does exactly this — and a status-only rule would still hide it.
+ *
+ * THE PREFIX ARM IS FOR THE ROWS ALREADY ON THE BOARD, and without it this fix
+ * would have shipped a transitional hole in its own negative control: every row
+ * `claim` wrote before this change carries `keyOf(item)` — a 60-character text
+ * prefix — and no id at all, so an id-only rule leaves a lane's OWN live item
+ * routable. Measured: q-2ba7f0c5's row, written minutes earlier by the
+ * pre-merge server, was offered back while it was in hand. Rows written from
+ * here carry the id (see `claim`), so the prefix arm is the compatibility half
+ * rather than the mechanism, and it is deliberately still SUBJECT-only.
+ */
+function boardHoldsItem(rows: WorkstreamsV1Row[], id: string, text: string): boolean {
+  const key = keyOf({ text } as QueueItem).replace(/\s+/g, " ").trim();
+  return rows.some((r) => {
+    if (!isInFlightStatus(r.status)) return false;
+    if (rowSubjectIds(r).includes(id)) return true;
+    const stream = String(r.stream).replace(/\s+/g, " ").trim();
+    return key.length >= 20 && stream.startsWith(key.slice(0, Math.min(key.length, 60)));
+  });
+}
+
+/**
+ * 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".
+ *
+ * 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:
+ *
+ *   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.
+ *
+ * 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.
+ */
+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*/, "");
+    return target.length >= 12 && body.startsWith(target);
+  });
+}
+
 // ---------- next_unblocked ----------
 
 export const nextUnblockedSchema = { project: z.string().min(1), repo: z.string().optional() };
@@ -166,12 +315,12 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // the item, which is how the memory was lost in the first place.
   const delivered = new Set<string>();
   const doneDoc = readDoc(repo, DONE_DOC);
-  const doneText = doneDoc?.text ?? "";
   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) {
-    // The id as written, so a recorded id matches the same token in either doc.
-    if (doneText.includes(i.id) || boardText.includes(i.id)) delivered.add(i.id);
+    if (boardHoldsItem(boardRows, i.id, String(i.text)) || doneRecordsDelivery(doneEntries, i.id, String(i.text))) delivered.add(i.id);
   }
 
   const open = items.filter((i) => !i.done && !delivered.has(i.id));
@@ -188,8 +337,33 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   // Skipped VISIBLY, same discipline as a blocked top item — never silently
   // dropped, so a caller can tell "nothing left for me" from "nothing left".
   const notClaimable: { item: string; sweepTag: string }[] = [];
+  // AWAITING A HUMAN (q-e334937d). "Unblocked" means dependency-free, and an
+  // item awaiting a ruling is dependency-free and unbuildable at once. Measured
+  // 2026-09-02: this verb offered q-11257590 as next; the lane read the
+  // acceptance PROSE to learn it awaited David, declined, and picked by hand —
+  // a read every lane offered it would pay again. The fact is now a FIELD on
+  // the item (`**[AWAITS:<who>]**`, read by the seam), never inferred from
+  // prose. Its own axis, checked FIRST: it is the most specific thing that can
+  // be true of an item, and "three items wait on a human" is a fact David can
+  // act on where "nothing to route" is not. Skipped for routing, never dropped.
+  //
+  // GATHERED OVER EVERY OPEN ITEM, NOT OVER `open` — measured on the real queue
+  // the first time this ran: q-11257590 carried the marker and appeared in NO
+  // bucket, because the board holds a "⏸ Parked — awaits David" row naming it
+  // and the delivered-join above reads any board mention as "handed out". The
+  // row written to WARN about the item was what hid it. Routing still honours
+  // the join; this report does not, because its reader is the human the item
+  // waits on, and a pending decision does not stop being pending when someone
+  // writes it on the board.
+  const awaitingDecision: { item: string; id: string; who: string; onBoard: boolean }[] = [];
+  for (const i of items) {
+    if (i.done) continue;
+    const who = awaitingOf(i);
+    if (who) awaitingDecision.push({ item: keyOf(i), id: i.id, who, onBoard: boardText.includes(i.id) });
+  }
   let pick: QueueItem | null = null;
   for (const { i } of ranked) {
+    if (awaitingOf(i)) continue; // reported above; never routed
     const tag = sweepTagOf(i);
     if (tag && /^canon(\.\d+)?$/.test(tag)) {
       notClaimable.push({ item: keyOf(i), sweepTag: tag });
@@ -223,9 +397,15 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     // would read a claimability gap as a dependency, which is a different
     // remedy (route it, don't wait for it).
     notClaimable,
+    // A THIRD AXIS, and not a variant of either above: `skipped` waits on
+    // another ITEM, `notClaimable` is not this caller's to take, and this waits
+    // on a HUMAN. The remedy differs each time (wait · route · ask), so one
+    // list covering them would leave the reader to infer which applies.
+    awaitingDecision,
     boardHunks: [
       ...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})`),
     ],
     // A SEPARATE AXIS, deliberately. See noDownstream().
     noDownstream: undiscriminating
@@ -422,7 +602,14 @@ export async function claimTool(args: { project: string; agentId: string; itemId
     };
   }
 
-  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${intendedRef}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
+  // THE ROW NAMES THE ITEM BY ID, so the delivered-join can recognise a row this
+  // verb itself wrote. Measured on the live board: `keyOf` is the item's text
+  // prefix and the recorded `⟨id⟩` token is not part of `text`, so NO
+  // claim-written row has ever carried an id — the join could only ever match
+  // HAND-WRITTEN rows, which is the opposite of what it was for. Stamping it
+  // makes the identification recorded rather than derived from a 60-character
+  // prose prefix that any rewording changes.
+  const boardHunk = `| ⟨${item.id}⟩ ${keyOf(item)} | ${args.agentId} | \`${intendedRef}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
 
   // 2.4b — THE VERB WRITES THE ROW. Reported by default, applied with
   // write:true, matching `land`. A returned hunk that a human pastes is the
@@ -459,6 +646,8 @@ export const landSchema = {
   repo: z.string().optional(),
   base: z.string().optional(),
   write: z.boolean().optional(),
+  /** One-line result, written after the citation on the closed item's line. */
+  result: z.string().optional(),
 };
 
 export async function landTool(args: {
@@ -468,6 +657,7 @@ export async function landTool(args: {
   repo?: string;
   base?: string;
   write?: boolean;
+  result?: string;
 }) {
   const repo = args.repo ?? process.cwd();
   const base = args.base ?? "main";
@@ -527,13 +717,46 @@ export async function landTool(args: {
   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.
+  // CLOSE = STATUS + CITATION. 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.
+  //
+  // AND THE LINE CITES WHAT CLOSED IT (q-6d21ff84). `doctor:queue-done-loop`
+  // requires a `[x]` item's FIRST LINE to cite the PR that DONE.md records —
+  // that strictness is what makes a closure machine-checkable, and the repo
+  // paid for it. This verb ticked the box and wrote DONE.md and left line 1
+  // uncited, so EVERY successful `land` turned main red at the next root gate
+  // and the coordinator hand-repaired a file the verb had just written
+  // (`c29becd`, and again on q-e334937d). The writer and the auditor were built
+  // to different contracts; the fix belongs in the writer, because loosening
+  // the auditor to accept what the writer emits is how a check stops being one.
+  //
+  // A SUFFIX, NOT A REWRITE. The existing text is preserved byte-for-byte as a
+  // prefix; ` · **closed by <ref>[ — <result>]**` is appended — the exact form
+  // q-40449919 carries after its manual repair. Line 1 only, because line 1 is
+  // all `item.text` is and all the check reads; a citation on a continuation
+  // line satisfies nothing (the occurrence-vs-position trap, hit twice).
+  //
+  // IDEMPOTENT: an item whose line already cites this PR (in any spelling
+  // `refsIn` ties to it) is left byte-identical, so a second `land` cannot
+  // double-cite and a hand-cited item is not re-cited.
   let queueChanged = false;
+  let citationAppended: string | null = null;
+  // The DONE entry and the emitted event describe the WORK, from the text the
+  // item had BEFORE the citation was appended — otherwise the summary would
+  // carry the citation the DONE line already ends with, twice on one line.
+  const originalText = target ? String(target.text) : null;
   if (target) {
     target.done = true;
     queueChanged = true;
+    const prRef = refsIn(args.pr)[0] ?? { raw: args.pr, repo: null, number: n };
+    const contextRepo = originRepoOf(repo);
+    const alreadyCited = refsIn(String(target.text)).some((r) => refsMatch(r, prRef, { contextRepo }));
+    if (!alreadyCited) {
+      citationAppended = ` · **closed by ${args.pr}${args.result ? ` — ${args.result.trim()}` : ""}**`;
+      target.text = `${target.text}${citationAppended}`;
+    }
   }
 
   const already = doneEntriesOf(d.doc).some((e) => new RegExp(`#${n}\\b`).test(String(e.ref ?? "")));
@@ -548,7 +771,7 @@ export async function landTool(args: {
   // 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 summary = originalText !== null ? summarize(originalText) : null;
 
   const doneLine =
     already || !summary ? null : `- [x] ${summary} — ${args.pr} · ${new Date().toISOString().slice(0, 10)}`;
@@ -565,8 +788,17 @@ export async function landTool(args: {
   // 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[] = [];
+  let stampedNotSupplied: string[] = [];
   if (args.write) {
-    if (queueChanged && writeDoc(repo, QUEUE_DOC, q.doc, q.text)) wrote.push(QUEUE_DOC);
+    if (queueChanged) {
+      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text);
+      if (w.written) wrote.push(QUEUE_DOC);
+      // Rows stamped that this call did not ask to touch. `queueItemId` is the
+      // one item the caller supplied, so anything else here is a row that
+      // arrived unstamped from somewhere: the absorption this verb would
+      // otherwise carry to main under its own name.
+      stampedNotSupplied = w.stamped.filter((id) => id !== args.queueItemId);
+    }
     if (doneLine) {
       const blocks = d.doc.blocks;
       let last = -1;
@@ -584,7 +816,7 @@ 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)) wrote.push(DONE_DOC);
+      if (writeDoc(repo, DONE_DOC, d.doc, d.text).written) wrote.push(DONE_DOC);
     }
   }
 
@@ -603,7 +835,7 @@ export async function landTool(args: {
   if (args.write && target) {
     const after = readDoc(repo, DONE_DOC);
     const recordText = after?.text ?? "";
-    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(target.text) };
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(originalText ?? "") };
     const derived = eventIsDerived(recordText, ev);
     if (!derived.ok) {
       events.refused.push(derived.error);
@@ -621,7 +853,31 @@ export async function landTool(args: {
     pr: `#${n}`,
     comparedAgainst: ref,
     landedIn: landedIn.slice(0, 8),
-    queueItem: target ? { id: target.id, closed: true, textUnchanged: true } : null,
+    // 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.
+    ...(stampedNotSupplied.length
+      ? {
+          stampedNotSupplied,
+          stampNote:
+            `recorded an id for ${stampedNotSupplied.length} queue item(s) this call did not supply (${stampedNotSupplied.join(", ")}) — ` +
+            `they arrived unstamped, most likely a raw text append, and would have reddened doctor:queue-id-recorded on whoever committed next. ` +
+            `Each id written is the one the item already had, so no value changed.`,
+        }
+      : {}),
+    queueItem: target
+      ? {
+          id: target.id,
+          closed: true,
+          // `textUnchanged` keeps its meaning — the priority and the body bytes
+          // the item had are all still there, in place. What is new is a SUFFIX
+          // on line 1, reported separately so a reader can tell "reworded" from
+          // "cited": null when the line already cited this PR.
+          textUnchanged: citationAppended === null,
+          bodyPreserved: true,
+          citationAppended,
+        }
+      : null,
     events,
     candidates: target
       ? undefined

package/src/tools/rooms.ts

@@ -60,6 +60,7 @@ import {
   setOffset,
   sysMsg,
   moveFile,
+  agentIdFromCursorFilename,
   STALE_MS,
   EVICT_MS,
   MAX_WAIT_MS,
@@ -284,7 +285,7 @@ export async function deleteRoomTool(args: { agentId: string; room: string; forc
   // a now-deleted file.
   const cursorsAdjusted: string[] = [];
   for (const fname of await listCursorFiles()) {
-    const id = fname.replace(/\.json$/, "");
+    const { id } = agentIdFromCursorFilename(fname);
     const cursorPath = path.join(CURSOR_DIR, fname);
     let touched = false;
     await updateJson<Cursor>(cursorPath, {}, (current) => {

package/src/tools/shared.ts

@@ -229,6 +229,24 @@ export type Cursor = {
 
 export type Source = "inbox" | "room" | "status";
 
+// q-40449919 (regression from 0.26.8): a `cursors/*.json` filename has TWO
+// shapes since the push/read cursor split (hooks/push-cursor.mjs) —
+// `<agent>.json` (read) and `<agent>.push.json` (push) — and every reader of
+// `listCursorFiles()` was stripping only the outer `.json`, so a push
+// cursor for `worker-3` parsed as an agent literally named `worker-3.push`.
+// That id is unregistered by construction (false `orphan-inboxes-cursors`),
+// and looking up ITS inbox resolves to a file that never existed, so its
+// real, correct offset compares as past-EOF against an empty file — the
+// bus's only error-level finding, driving `healthy:false` for a healthy
+// fleet. ONE parser, used everywhere a cursor filename becomes an agent id,
+// so the assumption cannot re-drift into some other reader the way the
+// filename shape itself drifted out from under the callers that predate it.
+export function agentIdFromCursorFilename(fname: string): { id: string; kind: "read" | "push" } {
+  const push = /^(.*)\.push\.json$/.exec(fname);
+  if (push) return { id: push[1], kind: "push" };
+  return { id: fname.replace(/\.json$/, ""), kind: "read" };
+}
+
 // Resolve the physical file for a (source, agent, channel) tuple.
 export function sourceFile(source: Source, agentId: string, room?: string): string {
   if (source === "inbox") return inboxFile(agentId);

package/src/tools/stall.ts

@@ -218,6 +218,34 @@ export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
 
 export const stallCheckSchema = { repo: z.string().optional(), stallMinutes: z.number().optional() };
 
+/**
+ * A row somebody is WORKING — the population the stall clock watches.
+ *
+ * It was `/🚧/` alone, and that read a fleet living in review as an EMPTY
+ * fleet (q-507e80c4). Measured on a consumer fleet 2026-09-02: a board of 3× `🔍 In
+ * Review` and 0× `🚧` returned `checked: 0, measurable: 0`, and `coord_away`
+ * armed at 0/0 — correct and vacuous at once. A clock watching nothing and a
+ * clock watching a healthy fleet return identical green.
+ *
+ * `🔍 In Review` is a lane with an owner and a branch that can stop moving
+ * exactly as an authoring lane can; the review that never gets re-gated is
+ * THE stall shape of a QA-gated fleet. It is read here, on the row as written
+ * — relabelling `🔍`→`🚧` to satisfy the old predicate was the item's
+ * forbidden move, because it satisfies a guard by editing what it reads and
+ * reports authoring lanes that do not exist.
+ *
+ * NOT widened further, deliberately: `⏸ Parked`, `⏳ Queued`, `⛔ Blocked`,
+ * `🚫 Unstaffable`, `✅ Done` have no lane to stall. Widening to everything
+ * would be the 0/0 defect inverted.
+ *
+ * One predicate, exported: `coord_away` measures coverage by calling
+ * `stall_check` and reading `checked`/`measurable`, so it inherits this
+ * population without a change of its own. Anything else that asks "which rows
+ * are in flight" should ask here rather than re-derive it from a glyph.
+ */
+export const IN_FLIGHT_STATUS = /🚧|🔍/;
+export const isInFlightStatus = (status: string): boolean => IN_FLIGHT_STATUS.test(status);
+
 export async function stallCheckTool(args: { repo?: string; stallMinutes?: number }) {
   const repo = args.repo ?? process.cwd();
   const limit = (args.stallMinutes ?? 30) * 60 * 1000;
@@ -226,7 +254,7 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
 
   const liveTransports = await loadLiveTransports();
   const rows = workstreamsV1RowsOf(parseWorkDoc(readFileSync(board, "utf8")));
-  const inFlight = rows.filter((r) => /🚧/.test(r.status));
+  const inFlight = rows.filter((r) => isInFlightStatus(r.status));
   const reg = await readJson<Record<string, { lastHeartbeat: number }>>(AGENTS_FILE, {});
   const now = Date.now();
   const hits: StallHit[] = [];