agent-coord-mcp 0.26.16 → 0.26.18

package/hooks/replay.mjs

@@ -0,0 +1,107 @@
+/*
+ * IS THIS INSTRUCTION ARRIVING FOR THE FIRST TIME, OR AGAIN?
+ *
+ * Phase 5.3 Task 21.2 asks for a property and deliberately names no mechanism:
+ * A REPLAYED INSTRUCTION MUST BE DISTINGUISHABLE FROM A LIVE ONE IN THE PANE,
+ * WITHOUT RELYING ON ANY AGENT'S RETAINED CONTEXT.
+ *
+ * WHY RETAINED CONTEXT CANNOT BE THE ANSWER — this is the whole reason the task
+ * forbids it. DM delivery is at-least-once by design (losing a message is worse
+ * than repeating one), so a crash, SIGTERM or dead pane between paste and cursor
+ * commit REDELIVERS. Today the redelivered bytes are IDENTICAL to the original,
+ * so the only thing that has ever caught a duplicate is an agent recognising the
+ * instruction — and that memory is destroyed two ways:
+ *
+ *   /clear       at a VISIBLE moment, at a task boundary, by an operator
+ *   compaction   SILENTLY and CONTINUOUSLY, with no command and no moment
+ *                anyone notices
+ *
+ * The aide's framing, which is stronger than the one I brought: the second is
+ * the case that matters, because there is no point at which anyone knows the
+ * memory is gone. A control whose only failure mode is invisible is not a
+ * control. Both were hit twice in one reconnect.
+ *
+ * THE SIGNAL IS THE RECEIPT LOG, WHICH IS ALREADY ON DISK. Receipts are stamped
+ * AFTER the payload is typed into the pane and the push cursor advances only
+ * after that, so the redelivery window is EXACTLY the window in which a receipt
+ * exists and the cursor has not moved. The evidence of a prior delivery is
+ * therefore already written down, by construction, before the redelivery can
+ * happen — nothing new has to be recorded and no agent has to remember anything.
+ *
+ * WHAT THE ABSENCE OF A MARKER DOES NOT MEAN. `prune` deletes receipts (default
+ * 7 days), and a receipt file that has been swept cannot report the delivery it
+ * once held. So an unmarked line means "no earlier delivery IS RECORDED", never
+ * "this is provably the first". That gap is bounded and not load-bearing —
+ * redelivery follows the original by seconds to minutes, while the sweep cutoff
+ * is days — but it is stated here rather than left for a reader to assume
+ * totality, which is the recurring defect this phase exists to remove.
+ *
+ * ONE GRAMMAR, TWO PRODUCERS. The local pusher reads its own receipts file; the
+ * remote pusher cannot see the server's filesystem, so the server annotates the
+ * message instead (readMessagesTool). Those two compute the same DATA by
+ * different routes and both render it through `replayMarker` here, so the pane
+ * cannot receive two different vocabularies for one fact.
+ */
+
+/**
+ * Prior deliveries per message id, from the text of a receipts JSONL file.
+ *
+ * Takes TEXT rather than a path so the parsing is exercisable without a
+ * filesystem — the reason cursor IO was moved into push-cursor.mjs.
+ * Unparseable lines are skipped: a corrupt tail must not blind the whole log.
+ */
+export function priorDeliveries(text) {
+  const out = new Map();
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.trim()) continue;
+    let r;
+    try {
+      r = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!r || typeof r.id !== "string") continue;
+    const seen = out.get(r.id);
+    const ts = Number.isFinite(r.ts) ? r.ts : undefined;
+    if (!seen) out.set(r.id, { deliveries: 1, ...(ts !== undefined ? { firstAt: ts } : {}) });
+    else {
+      seen.deliveries += 1;
+      // The FIRST delivery is the useful one to name: it tells a reader how
+      // long ago the instruction they are looking at was already handled.
+      if (ts !== undefined && (seen.firstAt === undefined || ts < seen.firstAt)) seen.firstAt = ts;
+    }
+  }
+  return out;
+}
+
+/**
+ * The `replay` annotation for a message about to be pasted, or undefined when
+ * no earlier delivery is recorded.
+ *
+ * `deliveries` counts receipts ALREADY on disk, so the attempt number of the
+ * delivery being rendered is that plus one.
+ */
+export function replayInfo(prior, id) {
+  const seen = id ? prior?.get(id) : undefined;
+  if (!seen || !(seen.deliveries > 0)) return undefined;
+  return { attempt: seen.deliveries + 1, ...(seen.firstAt !== undefined ? { firstAt: seen.firstAt } : {}) };
+}
+
+/**
+ * The pane-visible marker for a replay, or "" for a first delivery.
+ *
+ * It says three things, and the third is the one that makes it a control rather
+ * than a label: THIS IS NOT THE FIRST TIME, WHEN THE FIRST TIME WAS, and WHAT TO
+ * DO ABOUT IT. A reader with no retained context cannot infer the third, and
+ * "you may ignore a duplicate, an executor may not" is exactly the case where
+ * guessing is expensive — re-running a merge or a push because the instruction
+ * arrived twice is the failure at-least-once delivery pays for.
+ */
+export function replayMarker(replay) {
+  if (!replay || !(replay.attempt > 1)) return "";
+  const at = Number.isFinite(replay.firstAt) ? new Date(replay.firstAt) : null;
+  const when = at
+    ? ` · first delivered ${String(at.getUTCHours()).padStart(2, "0")}:${String(at.getUTCMinutes()).padStart(2, "0")}Z`
+    : "";
+  return `⟲ REPLAY (delivery ${replay.attempt}${when}) — ALREADY DELIVERED BEFORE; check server truth before acting, do not re-run it · `;
+}

package/hooks/tier.mjs

@@ -10,6 +10,7 @@
 // by convention, and a lowercase lookalike is chatter, not a work order.
 
 import { isGateRunner } from "./roles.mjs";
+import { replayMarker } from "./replay.mjs";
 
 // Typed protocol record → tier (Phase 8). The prefix table below is the same
 // vocabulary parsed out of text; reading the field instead removes the parse
@@ -211,6 +212,16 @@ export function injectLine(m) {
     const held = text.split("\n").length - 1;
     text = `${text.slice(0, nl)} [+${held} lines · record:${m.record.type} · retrieve_message id=${m.id}]`;
   }
+  // Phase 5.3 Task 21.2 — A REPLAY IS MARKED IN THE PANE, so telling it from a
+  // live instruction needs no retained context. Applied LAST so the marker is
+  // the first thing after the attribution header even when the record digest
+  // above has already rewritten `text` — a warning below the fold is an absent
+  // warning, and this line is often long.
+  //
+  // The header stays byte-identical, so the parse contract holds: attribution
+  // is still `[tag HH:MM from] ` and the marker is part of the TEXT, which is
+  // correct — it is something the reader must see, not metadata about routing.
+  text = `${replayMarker(m.replay)}${text}`;
   return `  [${tag} ${hhmm} ${m.from}] ${text}`;
 }
 

package/hooks/tmux-pusher.mjs

@@ -102,6 +102,7 @@ import { effectiveTier, isGateRunnerRole, TierQueue, formatBatch } from "./tier.
 import { isCi } from "./roles.mjs";
 import { mergeTransportMarker } from "./marker.mjs";
 import { readPushCursor, writePushCursor } from "./push-cursor.mjs";
+import { priorDeliveries, replayInfo } from "./replay.mjs";
 import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "./submit.mjs";
 
 const AGENT_ID = process.env.AGENT_COORD_ID;
@@ -583,6 +584,32 @@ async function injectViaTmux(batch) {
     );
     return [...batch];
   }
+  // Phase 5.3 Task 21.2 — STAMP THE REPLAY FACT BEFORE PASTING.
+  //
+  // Read once per inject, not per message: the receipt log is append-only and a
+  // single read is a consistent snapshot for the whole batch.
+  //
+  // WHY THIS FILE IS THE RIGHT PLACE, and why it can work at all: receipts are
+  // stamped AFTER a payload is typed (writeReceipts, below) and the push cursor
+  // advances only after the whole batch lands (commitOffsets, in flush). So a
+  // death anywhere in that window redelivers a message whose receipt is ALREADY
+  // on disk — the evidence exists before the duplicate can, without anyone
+  // having recorded anything for this purpose or remembered anything at all.
+  //
+  // Best-effort: an unreadable receipt log yields an empty map and therefore no
+  // markers, which is the honest direction. A missing marker means "no earlier
+  // delivery is RECORDED", never "this is provably the first" — see replay.mjs.
+  let prior = new Map();
+  try {
+    prior = priorDeliveries(readFileSync(RECEIPTS_FILE, "utf8"));
+  } catch {
+    // no receipts yet, or unreadable — every message renders as a first delivery
+  }
+  batch = batch.map((m) => {
+    const replay = replayInfo(prior, m?.id);
+    return replay ? { ...m, replay } : m;
+  });
+
   const undelivered = [];
   let run = [];
   const flushRun = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.16",
+  "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/scripts/coord-pusher.mjs

@@ -38,6 +38,8 @@
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "../hooks/submit.mjs";
+// The pane's parse-contract line, single-sourced — see the note above formatBatch.
+import { injectLine } from "../hooks/tier.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
@@ -248,38 +250,20 @@ async function flush() {
   }
 }
 
-// The per-message PARSE CONTRACT line — MUST stay byte-identical to
-// hooks/tier.mjs's injectLine (agent harnesses parse from/room/text out of
-// it). Compact form (v0.14.0): `  [<tag> <HH:MM> <from>] <text>`, tag drops
-// the leading "room ", timestamp is HH:MM UTC, no "from=" label. This pusher
-// is standalone (may deploy without hooks/), so the helper is duplicated
-// rather than imported; test/tier.test.mjs locks both to the same shape.
-function injectLine(m) {
-  const tag = String(m.tag ?? "").replace(/^room /, "");
-  const d = new Date(m.ts ?? 0);
-  const hhmm = `${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}`;
-  let text = m.text ?? "";
-  // Phase 8 Task 6: a TYPED record whose rendering spans lines is delivered as
-  // ONE attributed line — first line, a count of what was withheld, and the
-  // message id as the retrieval handle. Continuation lines used to arrive bare,
-  // with no `[tag HH:MM from]` header, so a parser could not attribute them.
-  //
-  // The handle is the message id, NOT a stashed copy: the full record is
-  // already persisted in rooms/<chan>.jsonl or inbox/<id>.jsonl, and
-  // retrieve_message reads it back by id (falling through to the append-only
-  // archive if compaction moved it). A cache would have had a TTL and lost the
-  // record permanently on expiry.
-  //
-  // Gated on `m.record`: a record-LESS multi-line message is untouched and
-  // still arrives unattributed past line 1, exactly as today. Task 6 does not
-  // fix hand-typed multi-line messages, and must not change their bytes.
-  const nl = text.indexOf("\n");
-  if (nl !== -1 && m.record && typeof m.record.type === "string" && m.id) {
-    const held = text.split("\n").length - 1;
-    text = `${text.slice(0, nl)} [+${held} lines · record:${m.record.type} · retrieve_message id=${m.id}]`;
-  }
-  return `  [${tag} ${hhmm} ${m.from}] ${text}`;
-}
+// THE PER-MESSAGE PARSE CONTRACT LINE IS IMPORTED, NOT COPIED.
+//
+// This was a duplicate of hooks/tier.mjs's `injectLine`, kept "byte-identical"
+// by a comment and locked by nothing, on the rationale that this pusher is
+// standalone and "may deploy without hooks/". THAT RATIONALE IS ALREADY FALSE:
+// the file imports ../hooks/submit.mjs at the top, so it cannot run without
+// hooks/ today and has not been able to for several releases. A copy kept in
+// step by a comment is two grammars the moment one is fixed — the same argument
+// the seam's phase-citation grammar records, where a second copy would have
+// kept a fixed bug alive in the other package with nothing to find it.
+//
+// Deleting the copy is what makes Task 21.2 land in BOTH panes: the replay
+// marker had to be added once rather than twice-and-hopefully-identically.
+// (the import itself sits with the other imports at the top of the file)
 
 function formatBatch(batch) {
   const lines = ["[agent-coord] msgs (pre-consumed, don't re-read):"];

package/src/server.ts

@@ -135,8 +135,13 @@ function jsonResult(data: unknown) {
 //     transport, or another live bound session) — that silently created a
 //     second session acting as an already-running agent (hit live 2026-07-06:
 //     a dev session bound itself to `<project>-liaison`). A live-id claim needs
-//     the agent's token or an explicit force (join/register params). See
-//     guardFirstClaim for how absent vs unreadable evidence is decided.
+//     the agent's TOKEN — `force` alone is refused against a provably live
+//     incumbent (q-314e0187, v0.26.0: `force` used to bypass this evidence
+//     check entirely, which is what let two live sessions hold
+//     `groundwork-kit-worker-3` at once on 2026-08-31). `force` still works
+//     for evidence the guard cannot verify at all, or an id verified absent.
+//     See guardFirstClaim for how absent vs unreadable vs live-but-unproven
+//     evidence is decided.
 //   - `trackSession` (stdio only): each successful bind writes a
 //     sessions/<id>.<pid>.<nonce>.json marker so doctor can SEE two live
 //     sessions bound to one id — closure state alone cannot be inspected
@@ -227,9 +232,14 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
   //   - a presented token must MATCH or the claim fails loudly, even when the
   //     id is not live — a wrong credential silently succeeding via the
   //     not-live path would teach callers that garbage tokens work;
-  //   - force is an explicit human/agent decision, honored before evidence;
-  //   - evidence that exists but cannot be read REFUSES (cannot-verify ≠
-  //     verified-absent; unreadable state must not disable the guard);
+  //   - evidence is gathered BEFORE `force` is consulted (q-314e0187): a live
+  //     PROVABLE incumbent can no longer be superseded by `force` alone — see
+  //     below. `force` is still honored, but only where it was never the
+  //     defect: unverifiable evidence, or a verified-absent id;
+  //   - evidence that exists but cannot be read REFUSES unless `force` is
+  //     passed (cannot-verify ≠ verified-absent; unreadable state must not
+  //     silently disable the guard, but an explicit override still works —
+  //     there is no incumbent to protect from being duplicated here);
   //   - a live id refuses, except when its live pusher types into THIS
   //     process's own tmux pane — two sessions cannot share a pane, so that
   //     is the same seat restarting (the routine fleet-restart case), not a
@@ -246,9 +256,9 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           `Mint one with scripts/coord-token.mjs add ${claimed} (then SIGHUP the bus), or pass force:true if you are certain.`,
       );
     }
-    if (args["force"] === true) return "force";
     const ev = await liveClaimEvidence(claimed, Date.now());
     if (!ev.verifiable) {
+      if (args["force"] === true) return "force";
       throw new Error(
         `cannot verify whether '${claimed}' is live: ${ev.reasons.join("; ")}. ` +
           `Refusing to bind rather than treating unreadable evidence as absence. ` +
@@ -257,14 +267,19 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     }
     if (ev.live) {
       if (ev.samePane && ev.boundElsewhere === 0) return "same-pane";
-      // A LEFTOVER SESSION IS NAMED AS ONE, AND force DOES NOT REMOVE IT.
-      //
-      // The old wording reported the same evidence and then offered `force:true`
-      // as the way through, which reads as a procedural step. It is not: forcing
-      // past a live session does not stop that process — it adds a second
-      // claimant to one identity, which is the condition that had two sessions
-      // holding worker-3's yesterday. The refusal papered over the thing it had
-      // just detected.
+      // A LEFTOVER SESSION IS NAMED AS ONE, AND force NO LONGER REMOVES IT
+      // EITHER — q-314e0187: `force:true` used to be checked BEFORE this
+      // evidence was even gathered (line order, not this message), so a
+      // provably-live incumbent was never actually protected — it just
+      // looked protected to anyone who did not pass `force`. Measured
+      // 2026-08-31: `doctor` found pid 7129 (via FORCE) and pid 9760 (via
+      // same-pane) both live and bound to `groundwork-kit-worker-3`
+      // simultaneously, and the bus log could not tell which one wrote a
+      // disputed message. `force` binding past a live session does not stop
+      // that process — it adds a second claimant to one identity, which is
+      // the condition that produced exactly that incident. So a provably
+      // live incumbent can now be superseded ONLY by its own token; `force`
+      // is refused here regardless of its value.
       //
       // A live TRANSPORT marker is a different fact and is not called a leak:
       // that pid is the pusher daemon, doing its job. Only a live SESSION
@@ -273,15 +288,20 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
       const leakLine = leaks.length
         ? ` LEFTOVER PROCESS${leaks.length > 1 ? "ES" : ""} HOLDING THIS IDENTITY: ` +
           leaks.map((l) => `pid ${l.pid} (via ${l.via})`).join(", ") +
-          `. Look at ${leaks.length > 1 ? "them" : "it"} before deciding — \`ps -p ${leaks.map((l) => l.pid).join(",")}\` — because force:true does NOT stop ${leaks.length > 1 ? "those processes" : "that process"}; it binds a SECOND session to one identity, and two sessions on one id is the defect this refusal exists to surface, not a step past it.`
+          `. Look at ${leaks.length > 1 ? "them" : "it"} before deciding — \`ps -p ${leaks.map((l) => l.pid).join(",")}\`.`
         : "";
       throw new Error(
-        `agent '${claimed}' is live on this bus (${ev.reasons.join("; ")}) — refusing to bind this fresh session to it.` +
+        `agent '${claimed}' is live on this bus (${ev.reasons.join("; ")}) — refusing to bind this fresh session to it` +
+          (args["force"] === true ? ", even with force:true" : "") +
+          `.` +
           leakLine +
-          ` If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}, or pass its token. ` +
+          ` A live incumbent can only be superseded with ITS OWN TOKEN now (mint one: scripts/coord-token.mjs add ${claimed}, then SIGHUP the bus) — ` +
+          `\`force:true\` binds a SECOND session to one identity rather than stopping the first, which is the defect this refusal exists to prevent, not a step past it. ` +
+          `If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}. ` +
           `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`,
       );
     }
+    if (args["force"] === true) return "force";
     return "tofu";
   }
 
@@ -349,7 +369,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "join",
-    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
+    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token — `force:true` no longer overrides a provably live incumbent (only the token does); it still works when liveness cannot be verified at all or the id is verified absent. Diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
     joinSchema,
     // join explicitly sets the session binding when unset, so each agent can
     // declare its identity via join rather than relying on env vars.
@@ -607,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>),
   );
@@ -642,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/board-ref.ts

@@ -65,6 +65,25 @@ const git = (repo: string, args: string[]): string | null => {
 };
 const resolves = (repo: string, ref: string): boolean => !!git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
 
+// Task 5.3/22.1's confirmation half: `docs/*` — a real historical cell value
+// — is a GLOB, and `git check-ref-format` refuses it as a branch name (a `*`
+// is not legal in a ref). A plain path like `docs/QUEUE.md` is, frustratingly,
+// ALSO a syntactically valid ref name (slashes and dots are both legal), so
+// this catches the glob shape precisely and does not claim to catch every
+// path — an honest partial fix is the property this task's own title asks
+// for ("every classifier can say I cannot tell"), not a heuristic that
+// pretends to be exhaustive.
+// Pure syntax check — never needs to run INSIDE a repo, so no `cwd` (unlike
+// every other helper here, which resolves refs against `repo`'s history).
+const isSyntacticallyValidRef = (name: string): boolean => {
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", name], { stdio: ["ignore", "pipe", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 /** The `\`ref\`` inside a `Branch · Worktree` cell, or "". */
 export function refInCell(cell: string): string {
   return (String(cell ?? "").match(/`([^`]+)`/)?.[1] ?? "").trim();
@@ -91,6 +110,19 @@ export function classifyBoardRef(
 
   const bare = raw.replace(/^origin\//, "");
 
+  // Task 5.3/22.1: CHECKED FIRST AND UNCONDITIONALLY — the original defect
+  // (`docs/*`) was previously only caught in a repo with NO origin remote at
+  // all (further down); confirmed live that in a repo WITH an origin — the
+  // normal case for every worktree this fleet actually runs — the same
+  // value fell through to the "unpushed" branch instead and was reported as
+  // "the branch has not been pushed", which is a confidently WRONG diagnosis
+  // for a path. `git check-ref-format` answers "could this even syntactically
+  // be a branch name" without touching the repo's history at all, so a glob
+  // is caught regardless of what else is true about this checkout.
+  if (!isSyntacticallyValidRef(bare)) {
+    return { kind: "path", why: `'${raw}' is not a syntactically valid branch name — it is a path or glob` };
+  }
+
   // A SHARED REF FIRST, because `main` resolves and would otherwise be measured.
   // Named explicitly rather than inferred from scoping, so the reason a reader
   // gets is the real one.
@@ -152,11 +184,24 @@ export function classifyBoardRef(
           `whether it is measurable depends on who last ran \`git fetch\`, which is a property of the reader rather than of the work.`,
       };
     }
+    // Task 5.3/22.2's fourth cause: "a pushed branch absent from this
+    // checkout" is NOT the same fact as "never pushed", and this check has
+    // no way to tell them apart without a network call it deliberately does
+    // not make (every other verdict here is a local git op only — adding
+    // one here would trade the offline property for one more cause). SAYING
+    // SO is the fix Task 22's own title asks for: a classifier that names
+    // an ABSENCE of evidence as a specific, confident cause is the exact
+    // shape "it is a path or glob" was wrong in — just moved one branch
+    // over. `'${remote}' does not exist` is the one fact this DOES know;
+    // everything past it is now framed as what it cannot distinguish rather
+    // than a guess dressed as a finding.
     return {
       kind: "unpushed",
       why:
-        `'${remote}' does not exist — the branch has not been pushed, so there is no shared evidence of activity yet. ` +
-        `That is an ABSENCE of evidence on a new lane, not a stall.`,
+        `'${remote}' does not resolve in THIS checkout — either the branch has never been pushed, or it WAS pushed and this ` +
+        `checkout's remote-tracking ref is simply stale (nobody has run \`git fetch\` here since). Cannot distinguish the two ` +
+        `without asking the remote, which this check deliberately does not do. Either way there is no LOCAL evidence of ` +
+        `activity, so it is not scored as a stall.`,
     };
   }