agent-coord-mcp 0.26.26 → 0.26.28

package/hooks/submit.mjs

@@ -323,7 +323,18 @@ export function readyProfileStartupLine(who) {
 // How many lines may sit below the input box's lower rule. Claude Code draws a footer there
 // (mode line, hints); a dialog, picker or autocomplete menu draws many more.
 export const READY_BOX_MAX_BELOW = 4;
-const RULE_RE = /^─{8,}$/;
+// ⟨q-c8032c5f⟩ herdr's `pane read --source visible` can draw a SHORT SINGLE-TOKEN pane label
+// into the middle of an otherwise-unbroken rule (measured on a live seat: 201 U+2500 dashes
+// with " qa2 " spliced in near the end) — herdr's own frame chrome overlaid onto the exact
+// row Claude Code drew as a plain rule, not something Claude Code's own render ever does.
+// A pure exact-match (`/^─{8,}$/`) read that as "not a rule at all" and held every push to
+// that seat: the line WAS the rule, annotated, and the annotation is what broke the match —
+// not the pane, not the transport, not the seat. Tolerate exactly one such label (a single
+// run of non-space, non-dash characters, flanked by spaces, flanked by dashes on both sides)
+// and nothing looser: multi-word content, a label with no dashes on one side, or two labels
+// still fail — those are genuinely not a rule, and loosening further would just move the
+// false-refusal into a false-accept instead of fixing it.
+const RULE_RE = /^─{8,}(?: [^\s─]+ )?─*$/;
 const BOX_LINE_RE = /^❯(?:\s|$)/;
 const MAX_DRAFT_LINES = 20;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.26.26",
+  "version": "0.26.28",
   "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": {
@@ -50,6 +50,7 @@
     "anthropic",
     "ipc",
     "chat",
+    "herdr",
     "tmux"
   ],
   "license": "MIT",

package/scripts/coord-stall-clock.mjs

@@ -76,6 +76,13 @@ const duty = argv.duty ? String(argv.duty) : null;
 // and never the lane's agent. From --board-owner, else the board's own Rooms
 // table (`boardOwnerOf`), else the duty officer with a line saying so.
 const boardOwnerFlag = argv["board-owner"] ? String(argv["board-owner"]) : null;
+// ⟨q-11257590⟩ — coordinator absence has NO duty owner and NO board owner: the
+// coordinator seat itself is the thing missing. David's ruling: "if we have a
+// comms issue that just needs to be surfaced to me then i tackle it" — so this
+// audience gets its own recipient, defaulting to the literal id `david` (the
+// registered human seat on this bus) rather than folding into board-owner,
+// which would address the DM to the very seat that is absent.
+const davidFlag = String(argv.david ?? "david");
 const from = String(argv.from ?? "coord-stall-clock");
 const stallMinutes = argv["stall-minutes"] ? Number(argv["stall-minutes"]) : undefined;
 
@@ -114,10 +121,15 @@ try {
       case "lane-left-population": return `- ${h.agentId}: "${h.stream}" LEFT the scored population since the last run with no closing state — its row is gone; close it through a state (✅/⏸/⛔), never by deletion`;
       case "unread-delete-claim": return `- ${h.agentId}: closing line for ${h.pr === null ? "a merge" : `#${h.pr}`} ${h.minutes}m ago asserts a branch deletion it did not show it read — say \`remote ref read: 0 refs at <ts>\` or \`delete requested\``;
       case "merge-window-write": return `- ${String(h.sha).slice(0, 7)} (${h.author}) wrote a record document ${h.secondsIntoWindow}s into MERGE WINDOW #${h.pr} — hold queue/board/DONE writes between the window's open and close`;
+      case "coordinator-absent": return `- COORDINATOR ABSENT: '${h.agentId}' — ${h.why}`;
       default: return `- ${JSON.stringify(h)}`;
     }
   };
-  const byAudience = { duty: r.hits.filter((h) => h.audience === "duty"), "board-owner": r.hits.filter((h) => h.audience !== "duty") };
+  const byAudience = {
+    duty: r.hits.filter((h) => h.audience === "duty"),
+    "board-owner": r.hits.filter((h) => h.audience === "board-owner"),
+    david: r.hits.filter((h) => h.audience === "david"),
+  };
   let boardOwner = boardOwnerFlag;
   if (!boardOwner) {
     const bp = path.join(repo, "docs/WORKSTREAMS.md");
@@ -144,12 +156,24 @@ try {
     }
   }
 
+  if (byAudience.david.length) {
+    // No fallback and no "nobody" case: David's ruling was explicit — this
+    // audience exists precisely because nothing else in the fleet can act on
+    // it, so it always addresses `davidFlag` (default `david`), never the
+    // board owner (who may BE the absent coordinator) and never the duty officer.
+    await sendMessageTool({
+      from, to: davidFlag,
+      record: { type: "blocker", payload: { summary: `stall_check — coordinator absence: ${byAudience.david.map((h) => h.agentId).join(", ")}` } },
+      text: `BLOCKER: stall_check — ${byAudience.david.length} coordinator-absence finding(s). Nothing in the fleet can act on this; it is surfaced to you per your ruling ("coord should never be absent in reality... if we have a comms issue that just needs to be surfaced to me then i tackle it").\n${byAudience.david.map(line).join("\n")}${trailer}`,
+    });
+  }
+
   // Null result to stdout every run: the log is the record a human reads, and a
   // trigger that only speaks when it fires cannot be told from a broken one.
   const um = r.unmeasurable?.length ? `, ${r.unmeasurable.length} unmeasurable` : "";
   console.log(
     r.hits.length
-      ? `[stall-clock] HIT ${r.hits.length}/${r.checked}${um} — duty:${byAudience.duty.length}${duty ? ` → ${duty}` : " (NO DUTY OFFICER SET, no DM)"} · board-owner:${byAudience["board-owner"].length}${byAudience["board-owner"].length ? ` → ${boardOwner ?? (duty ? `${duty} (fallback)` : "nobody")}` : ""}`
+      ? `[stall-clock] HIT ${r.hits.length}/${r.checked}${um} — duty:${byAudience.duty.length}${duty ? ` → ${duty}` : " (NO DUTY OFFICER SET, no DM)"} · board-owner:${byAudience["board-owner"].length}${byAudience["board-owner"].length ? ` → ${boardOwner ?? (duty ? `${duty} (fallback)` : "nobody")}` : ""} · david:${byAudience.david.length}${byAudience.david.length ? ` → ${davidFlag}` : ""}`
       : `[stall-clock] MISS 0/${r.checked}${um} — no DM, run recorded`,
   );
 } catch (e) {

package/src/bind.ts

@@ -0,0 +1,40 @@
+/**
+ * ⟨q-79ee2086⟩ Where the bus listens.
+ *
+ * ⛔ ITS OWN MODULE BECAUSE `server.ts` RUNS ON IMPORT. `main()` is invoked at the bottom of that
+ * file, so importing it to reach a helper starts a real server and never returns — a test that did
+ * so would hang rather than fail, which is worse. These two predicates decide who can reach the bus,
+ * so they must be reachable by a test without standing one up.
+ */
+
+/**
+ * `AGENT_COORD_BIND` as a comma-separated LIST.
+ *
+ * ⛔ A LIST RATHER THAN `0.0.0.0`, and the difference is the whole point. `0.0.0.0` binds every
+ * interface this host has now AND every one it gains later — a VPN coming up silently widens the
+ * listener with nothing in any log. A list states exactly which doors are open, is reviewable on
+ * disk, and cannot grow behind the operator's back.
+ *
+ * Empty or unset is `127.0.0.1`, the safe default. Duplicates collapse — the same address twice
+ * would otherwise be a self-inflicted `EADDRINUSE` at startup, read as a real conflict. Order of
+ * first appearance is preserved so the startup log matches what the operator wrote.
+ */
+export function parseBindList(raw: string | undefined): string[] {
+  const parts = String(raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (parts.length === 0) return ["127.0.0.1"];
+  return [...new Set(parts)];
+}
+
+/**
+ * Loopback exactly — the set that needs no per-agent token and no out-of-band-security assertion,
+ * because nothing off this host can reach it.
+ *
+ * ⚠ AN EXACT MATCH, never a prefix or a regex. `127.0.0.1` is loopback; `127.0.0.10` and
+ * `localhost.attacker.net` are not, and a gate satisfiable by a lookalike string is not a gate.
+ */
+export function isLoopbackAddr(addr: string): boolean {
+  return addr === "127.0.0.1" || addr === "localhost" || addr === "::1";
+}

package/src/capabilities.ts

@@ -48,10 +48,11 @@ import { injectLine } from "../hooks/tier.mjs";
 import { findControlByte } from "../hooks/control-bytes.mjs";
 // ⟨q-15d763dc⟩ The ready-box guard's profile, as this process read it from its own env at start.
 // @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
-import { readyProfile } from "../hooks/submit.mjs";
+import { readyProfile, readReadyBox } from "../hooks/submit.mjs";
 import { subscriptionHealth } from "./tools/events.js";
 import {
   configuredTransport,
+  resolveConfiguredTransport,
   runningTransport,
   isTmuxKind,
   targetOf,
@@ -388,6 +389,78 @@ const PROBES: Probe[] = [
       }
     },
   },
+  {
+    // ⛔⛔ ⟨q-c8032c5f⟩ — the ready-box guard HELD EVERY PUSH to a live seat (ticks 191,
+    // delivered 0, held 98) reporting "the ❯ line has no ─ rule directly above it" against a pane
+    // that WAS ready. herdr splices the pane's own label into the frame, so the rule Claude Code
+    // drew as plain dashes arrives as `──… qa2 ─`. `RULE_RE` demanded an unbroken dash line and
+    // read the annotated one as not-a-rule: a false negative in the matcher, reported as a fact
+    // about the pane. The seat stayed queued and functional for PULL and simply never WOKE.
+    //
+    // ⚠ THE NEGATIVES ARE THE PROBE. Accepting the label is one line; accepting it WITHOUT opening
+    // a false-accept is the property. A matcher that took any annotated rule would pass a
+    // positive-only probe while typing into dialogs and menus — so a multi-word label, a label
+    // with no dash after it, and two labels are each asserted REFUSED alongside the accept.
+    id: "ready-box-tolerates-pane-label",
+    since: "0.26.27",
+    run: () => {
+      const D = "─".repeat(60);
+      const screen = (rule: string) => [`${D} above ${D}`, rule, "❯", D, "  ⏵⏵ bypass permissions on"].join("\n");
+      const readyOf = (rule: string) => readReadyBox(screen(rule), "claude-code") as { ready: boolean; reason?: string };
+
+      const labelled = readyOf(`${D} qa2 ${D}`).ready === true; // the live failure, now accepted
+      const plain = readyOf(D).ready === true; // control: the un-annotated rule must still work
+      const multiWord = readyOf(`${D} two words ${D}`).ready === false;
+      const noTrailingDash = readyOf(`${D} qa2 `).ready === false;
+      const twoLabels = readyOf(`${D} a ${D} b ${D}`).ready === false;
+
+      const present = labelled && plain && multiWord && noTrailingDash && twoLabels;
+      return {
+        present,
+        evidence: `herdr-labelled rule accepted=${labelled} · plain rule still accepted=${plain} · REFUSED: multi-word=${multiWord}, no-trailing-dash=${noTrailingDash}, two-labels=${twoLabels} -> present=${present}`,
+      };
+    },
+  },
+  {
+    // ⟨q-d404a6f6⟩/⟨q-9e0072b3⟩ — `configuredSource` is a WIRE VALUE, and #384 changed it from
+    // "config" to "machine-config" because `config.json` is machine-scoped, not fleet-wide. Anything
+    // comparing `configuredSource === "config"` — the console, a gate, a seat checking its own
+    // status — reads one answer from a 0.26.27 server and another from this one.
+    //
+    // ⚠ WHICH IS WHY IT NEEDS A PROBE AND NOT JUST A BUMP: a renamed output is invisible to every
+    // artefact except the one that calls it. ⟨q-9e0072b3⟩ was filed because the tree carried this
+    // change while the registry did not, and nothing in either could say so — the version label was
+    // identical on both sides of a behaviour difference.
+    id: "transport-source-is-machine-scoped",
+    since: "0.26.28",
+    run: () => {
+      // ⛔ THIS PROBE MUST PROVE A PROPERTY OF THE CODE, NEVER A FACT ABOUT THIS MACHINE.
+      // The first version called `configuredTransport()` directly — which reads THIS seat's
+      // real config.json off disk — and `check-baseline-declared` correctly flagged that as an
+      // UNDECLARED mutable-baseline read: a probe run by `check-probe-coverage.mjs` in the gate
+      // chain has no business depending on whatever transport this one box happens to have
+      // configured. It also, as a side effect, called `configuredTransport()` uncaught: that
+      // throws by design on an unconfigured seat, and `probeCapabilities`'s outer catch turned
+      // the throw into an undiscriminated `present:false`, breaking `capabilities.ok` for any
+      // fresh/unregistered seat (test/status-capabilities.test.mjs's unregistered-agent case).
+      //
+      // ✅ FIXED BOTH WAYS BY CALLING `resolveConfiguredTransport` — the PURE decision
+      // `configuredTransport()` delegates to — WITH CONSTRUCTED INPUTS instead: two cases, one
+      // for each live source, built here rather than read from anywhere. Nothing outside this
+      // process is touched, so there is no baseline to declare, and there is no live-config
+      // state that could throw.
+      const machineConfig = resolveConfiguredTransport({ fileHasTransport: true, fileTransport: "herdr", env: undefined });
+      const env = resolveConfiguredTransport({ fileHasTransport: false, fileTransport: undefined, env: "herdr" });
+      const sources = [machineConfig.source, env.source] as const;
+      const known = sources.every((s) => s === "machine-config" || s === "env");
+      const retired = (sources as readonly string[]).includes("config");
+      const present = known && !retired;
+      return {
+        present,
+        evidence: `constructed machine-config case -> source=${JSON.stringify(machineConfig.source)} · constructed env case -> source=${JSON.stringify(env.source)} · in current vocabulary={machine-config,env}=${known} · either is retired "config"=${retired} -> present=${present}`,
+      };
+    },
+  },
   {
     // ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — the external tick, probed by CALLING the code that
     // decides what a reading MEANS (every probe here is synchronous, so the async read is
@@ -534,8 +607,9 @@ export type TransportCapability = {
   agrees: boolean;
   /** What was called and what came back. */
   evidence: string;
-  /** Where `configured` came from — config file or env. ⟨q-ec020f6a⟩: no built-in default. */
-  configuredSource: "config" | "env";
+  /** Where `configured` came from — this machine's config.json, or env. ⟨q-d404a6f6⟩: config.json is
+   *  machine-scoped, not fleet-wide. ⟨q-ec020f6a⟩: no built-in default. */
+  configuredSource: "machine-config" | "env";
   /**
    * 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

package/src/server.ts

@@ -118,6 +118,7 @@ import {
   isPidAlive,
 } from "./tools/index.js";
 import { queueWriteSchema, queueWriteTool } from "./tools/queue-write.js";
+import { parseBindList, isLoopbackAddr } from "./bind.js";
 
 function jsonResult(data: unknown) {
   return {
@@ -939,19 +940,27 @@ async function startHttp(port: number): Promise<void> {
         "to pre-bind sessions to identities at connect time.",
     );
   }
-  const bindAddr = process.env.AGENT_COORD_BIND ?? "127.0.0.1";
+  // ⟨q-79ee2086⟩ A LIST, because one address forces a choice the deployment should not have to
+  // make. The bus was reachable on the Tailscale address OR the LAN and never both, so adding a
+  // second machine meant MOVING the bind and breaking every local seat's config at the same moment.
+  // A single value still parses to a one-element list, so existing deployments are unaffected.
+  const bindAddrs = parseBindList(process.env.AGENT_COORD_BIND);
   const sharedExpected = sharedToken ? `Bearer ${sharedToken}` : null;
 
   // Fail-closed network gate. A non-loopback bind is a real network listener, so
   // it must have (a) enforced per-agent identity and (b) a secured transport. We
   // refuse rather than warn: a shared/advisory token lets any node impersonate
   // any agent, and plaintext leaks bearer tokens to anyone on the path.
-  const isLoopbackBind =
-    bindAddr === "127.0.0.1" || bindAddr === "localhost" || bindAddr === "::1";
-  if (!isLoopbackBind) {
+  //
+  // ⛔ EVALUATED OVER THE WHOLE LIST, NOT PER ADDRESS. `127.0.0.1,192.168.1.10` must NOT pass
+  // because one entry happens to be loopback — the listener on the second address is exposed
+  // whatever the first one is, and a gate that a caller can satisfy by prepending a loopback
+  // address is not a gate. The offending address is NAMED so the refusal is actionable.
+  const exposed = bindAddrs.filter((a) => !isLoopbackAddr(a));
+  if (exposed.length > 0) {
     if (!bound) {
       console.error(
-        `[agent-coord-mcp] refusing to bind ${bindAddr} without per-agent tokens: a ` +
+        `[agent-coord-mcp] refusing to bind ${exposed.join(", ")} without per-agent tokens: a ` +
           `shared/advisory token lets any node impersonate any agent. Create ` +
           `~/agent-coord/tokens.json (per-agent, enforced identity) for network binds.`,
       );
@@ -959,7 +968,7 @@ async function startHttp(port: number): Promise<void> {
     }
     if (process.env.AGENT_COORD_INSECURE !== "1") {
       console.error(
-        `[agent-coord-mcp] refusing plaintext bind to ${bindAddr}: bearer tokens would ` +
+        `[agent-coord-mcp] refusing plaintext bind to ${exposed.join(", ")}: bearer tokens would ` +
           `travel in cleartext. Put the bus behind TLS or a private overlay ` +
           `(Tailscale/WireGuard), then set AGENT_COORD_INSECURE=1 to acknowledge the ` +
           `transport is secured out-of-band.`,
@@ -1092,7 +1101,11 @@ async function startHttp(port: number): Promise<void> {
     return sharedExpected && authHeader === sharedExpected ? { ok: true } : { ok: false };
   }
 
-  const http = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+  // ⛔ ONE HANDLER, N SERVERS. Node binds a single address per `http.Server`, so a list of
+  // addresses is a list of SERVERS — not a loop over `listen`. They share this closure, and with
+  // it the session map and the bound-agent map, so a session created on one address is the same
+  // session on another: the addresses are doors into one bus, not separate buses.
+  const handler = async (req: IncomingMessage, res: ServerResponse) => {
     try {
       // Unauthenticated liveness probe so reverse proxies / orchestrators can
       // health-check without needing a credential.
@@ -1150,18 +1163,44 @@ async function startHttp(port: number): Promise<void> {
         res.end("internal error\n");
       }
     }
-  });
+  };
 
-  http.listen(port, bindAddr, () => {
-    const mode = bound ? `pre-bound (${getTokenMap()?.size ?? 0} agents)` : "TOFU";
-    console.error(`[agent-coord-mcp] http listening on ${bindAddr}:${port} — identity ${mode}`);
-    if (bindAddr !== "127.0.0.1" && bindAddr !== "localhost") {
-      console.error(
-        `[agent-coord-mcp] WARNING: bound to ${bindAddr} without TLS. Front with a TLS reverse proxy ` +
-          `(or restrict to a private network e.g. Tailscale/WireGuard) before exposing publicly.`,
-      );
-    }
-  });
+  const mode = bound ? `pre-bound (${getTokenMap()?.size ?? 0} agents)` : "TOFU";
+  await Promise.all(
+    bindAddrs.map(
+      (addr) =>
+        new Promise<void>((resolve) => {
+          const server = createServer(handler);
+          // ⛔ FAIL CLOSED ON A BIND ERROR. A declared address that cannot be bound —
+          // EADDRNOTAVAIL because the interface is not up yet, EADDRINUSE because something
+          // else holds the port — must REFUSE, not leave the daemon serving the subset that
+          // happened to work. A bus up on one of two declared addresses while saying nothing is
+          // the silent-partial-success shape this codebase refuses everywhere else: the seats on
+          // the missing address fail to connect and nothing explains why. launchd's KeepAlive
+          // already covers the honest case (tailscaled has not brought utun0 up yet) by retrying.
+          server.on("error", (err: NodeJS.ErrnoException) => {
+            console.error(
+              `[agent-coord-mcp] refusing to start: cannot bind ${addr}:${port} (${err.code ?? err.message}). ` +
+                `AGENT_COORD_BIND declares ${bindAddrs.length} address(es) and every one must bind — ` +
+                `serving only some would leave seats on the others unable to connect, with nothing said.`,
+            );
+            process.exit(1);
+          });
+          server.listen(port, addr, () => {
+            // One line PER ADDRESS: a single "http listening on …" would be read as the whole
+            // picture, and the operator needs to see which doors are actually open.
+            console.error(`[agent-coord-mcp] http listening on ${addr}:${port} — identity ${mode}`);
+            if (!isLoopbackAddr(addr)) {
+              console.error(
+                `[agent-coord-mcp] WARNING: bound to ${addr} without TLS. Front with a TLS reverse proxy ` +
+                  `(or restrict to a private network e.g. Tailscale/WireGuard) before exposing publicly.`,
+              );
+            }
+            resolve();
+          });
+        }),
+    ),
+  );
 }
 
 main().catch((err) => {

package/src/tools/herdr-tail.ts

@@ -39,7 +39,7 @@
  */
 import { readFileSync, statSync } from "node:fs";
 import { inboxFile, roomFile, getRooms, transportFile } from "../store.js";
-import { activeTransport, HERDR, type Transport, type TransportMarker } from "../transports/index.js";
+import { activeTransport, HERDR, targetOf, type Transport, type TransportMarker } from "../transports/index.js";
 import { renderForPane, advancePushCursor, readPushCursorFor, type Message } from "./herdr-delivery.js";
 import { newMessagesIn } from "./jsonl-offsets.js";
 
@@ -103,9 +103,19 @@ export async function tailOnce(
     ctx?: TailContext;
     markerOf?: (agentId: string) => TransportMarker | null;
     roomsOf?: () => Promise<Record<string, { members?: string[] }>>;
+    /**
+     * ⟨q-1ce5bc97⟩ step 1 — EVERY push outcome, logged, not just the ones that end up in
+     * `held`. Before this, bus-daemon.err.log recorded no push outcomes at all: a
+     * `delivered` and a silently-dropped `typed-unconfirmed` looked identical from the
+     * log, because nothing wrote either one. Injectable so a test can capture lines
+     * without a real stderr; defaults to `console.error` — the same sink every other
+     * diagnostic in this process already writes to.
+     */
+    log?: (line: string) => void;
   } = {},
 ): Promise<TailOutcome> {
   const out: TailOutcome = { delivered: [], held: [] };
+  const log = opts.log ?? ((l: string) => console.error(l));
   const t = opts.transport ?? activeTransport();
   if (!t || t.kind !== HERDR) return { ...out, idle: "this server's transport is not herdr — the tail is for a herdr seat's own inbox" };
   const ctx = opts.ctx ?? newContext();
@@ -155,6 +165,13 @@ export async function tailOnce(
       const rendered = await renderForPane(msg as unknown as Message, agentId, where);
       let r: { delivered: boolean; error?: string; verified?: boolean; safeToRetry?: boolean; outcome?: string };
       try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, safeToRetry: false, error: (e as Error).message }; }
+      // ⟨q-1ce5bc97⟩ step 1(b) — EVERY push outcome, logged, before any branch decides what to do
+      // with it. Not just the ones that end up `held`: a `delivered` needs a line too, or the
+      // log can never distinguish "nothing was owed" from "something was pushed and it worked".
+      log(
+        `[herdr-tail] push id=${String(msg.id ?? "?")} target=${targetOf(marker) ?? "?"} outcome=${r.outcome ?? (r.delivered ? "delivered" : "unknown")}` +
+          (r.error ? ` reason=${JSON.stringify(r.error)}` : ""),
+      );
       if (!r.delivered && r.safeToRetry === true) {
         // HELD: the transport sent NO key (no ready input box, a draft, a dialog, an unreadable pane).
         // Nothing moves and the message is retried next tick, which costs only a screen read. Stop

package/src/tools/stall.ts

@@ -134,10 +134,20 @@ const haltFile = () => path.join(ROOT, "halt.json");
  *   board-owner  bookkeeping: a row pointing at a landed branch, a routed item
  *                with no row, a merge with no verdict comment. Somebody must
  *                fix the RECORD; the lane's owner did nothing wrong.
+ *   david        ⟨q-11257590⟩ nobody IN THE FLEET can act on this: the coordinator
+ *                seat itself is the thing missing, so there is no duty owner and no
+ *                board-owner left to fix the record. David's own ruling: "coord
+ *                should never be absent in reality... if we have a comms issue that
+ *                just needs to be surfaced to me then i tackle it" — this audience
+ *                exists so a relayer routes it to him and nowhere else.
  */
-export type HitAudience = "duty" | "board-owner";
+export type HitAudience = "duty" | "board-owner" | "david";
 export const audienceOf = (kind: StallHitBody["kind"]): HitAudience =>
-  kind === "stale-row" || kind === "routed-without-row" || kind === "unverdicted-merge" || kind === "merge-window-write" || kind === "lane-left-population" ? "board-owner" : "duty";
+  kind === "coordinator-absent"
+    ? "david"
+    : kind === "stale-row" || kind === "routed-without-row" || kind === "unverdicted-merge" || kind === "merge-window-write" || kind === "lane-left-population"
+      ? "board-owner"
+      : "duty";
 const withAudience = (hits: StallHitBody[]): StallHit[] => hits.map((h) => ({ ...h, audience: audienceOf(h.kind) }) as StallHit);
 export type StallHit = StallHitBody & { audience: HitAudience };
 export type StallHitBody =
@@ -226,7 +236,19 @@ export type StallHitBody =
    * abandoned or genuinely unlanded — so the hit SAYS so, or a true alarm
    * with a false implication teaches the reader to ignore the axis.
    */
-  | { kind: "unproposed-branch"; agentId: string; branch: string; head: string; ahead: number; minutes: number; note: string };
+  | { kind: "unproposed-branch"; agentId: string; branch: string; head: string; ahead: number; minutes: number; note: string }
+  /**
+   * ⟨q-11257590⟩ — David's ruling: coordinator absence is a FAULT to be surfaced,
+   * never a state to be silently covered by a stand-in. `agentId` is read from the
+   * board's own Rooms table (`boardOwnerOf`), the same name every seat is told at
+   * `join` — never hardcoded, so a renamed coordinator seat is still found. Fires
+   * when the seat the board itself names has no registry entry at all, or has one
+   * but no currently-live transport marker (`loadLiveTransports`, which already
+   * verifies pid/pane/remote-heartbeat liveness for every transport kind — this
+   * reuses that verdict rather than re-deriving it). A present-and-active
+   * coordinator produces NO hit: the negative control this row's acceptance requires.
+   */
+  | { kind: "coordinator-absent"; agentId: string; why: string };
 
 /* ────────────────────────────────────────────────────────────────────────────
  * ⟨q-6f0a3d81⟩ — THE HANDOVER IS THE THING BEING MEASURED, AND EVERY INSTRUMENT
@@ -1345,6 +1367,29 @@ export async function stallCheckTool(
     }));
   const now = Date.now();
   const hits: StallHitBody[] = [];
+  // ⟨q-11257590⟩ — COORDINATOR ABSENCE IS A FAULT, SURFACED, NEVER COVERED. Read the
+  // seat's own name from the board (`boardOwnerOf`, the Rooms table's "topic owner"
+  // cell — the same identity every seat is told at `join`), not hardcoded, so a
+  // renamed or re-elected coordinator is still found. `reg` and `liveTransports` are
+  // already loaded above for the role rows; this reuses their verdicts rather than
+  // re-deriving liveness. NO board owner named → nothing to check, not a hit: an
+  // unnamed owner is a board-authoring gap, a different row's problem.
+  const coordId = boardOwnerOf(boardText);
+  if (coordId) {
+    if (!reg[coordId]) {
+      hits.push({
+        kind: "coordinator-absent", agentId: coordId,
+        why: `the board names '${coordId}' as coordinator (topic owner) but the bus has no registry entry for it — never joined, or evicted`,
+      });
+    } else if (!liveTransports.has(coordId)) {
+      hits.push({
+        kind: "coordinator-absent", agentId: coordId,
+        why: `'${coordId}' is registered but has no live transport marker right now — registered once, unreachable now`,
+      });
+    }
+    // Present AND active → no hit. This is the row's required negative control: a
+    // healthy coordinator must not surface, or this becomes a standing false alarm.
+  }
   /** The base's tip, for telling an empty claim-time push from a lane with commits. */
   let baseTip: string | null = null;
   for (const cand of ["origin/main", "origin/master", "main", "master"]) {

package/src/tools/transport.ts

@@ -1634,6 +1634,16 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     if (!counts.has(file)) counts.set(file, await scanJsonl(file));
     return counts.get(file)!;
   };
+  /** A PUSH cursor's bound: bytes on disk, the same figure `advancePushCursor` writes. ⟨q-f018dd51⟩ */
+  const sizes = new Map<string, number>();
+  const byteSizeOf = async (file: string) => {
+    if (!sizes.has(file)) {
+      let n = 0;
+      try { n = (await fsp.stat(file)).size; } catch { n = 0; }
+      sizes.set(file, n);
+    }
+    return sizes.get(file)!;
+  };
 
   // 4. Cursor offsets past end-of-file (would return [] forever).
   //
@@ -1645,20 +1655,46 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   // agent's inbox in the first place.
   {
     const broken: string[] = [];
+    const lagging: string[] = [];
     for (const fname of await listCursorFiles()) {
       const { id, kind } = agentIdFromCursorFilename(fname);
       const cursorPath = path.join(CURSOR_DIR, fname);
       const cursor = await readJson<Cursor>(cursorPath, {});
       const overflow: string[] = [];
-      const inboxMax = (await countFor(inboxFile(id))).parsed;
-      if ((cursor.inboxOffset ?? 0) > inboxMax) overflow.push(`inboxOffset ${cursor.inboxOffset}>${inboxMax}`);
-      const roomMax = (await countFor(ROOM_FILE)).parsed;
-      if ((cursor.roomOffset ?? 0) > roomMax) overflow.push(`roomOffset ${cursor.roomOffset}>${roomMax}`);
-      const statusMax = (await countFor(STATUS_FILE)).parsed;
-      if ((cursor.statusOffset ?? 0) > statusMax) overflow.push(`statusOffset ${cursor.statusOffset}>${statusMax}`);
+      // ⛔⛔ THE TWO CURSOR KINDS ARE IN DIFFERENT UNITS, AND CONFLATING THEM ARMED A DESTRUCTIVE FIX.
+      // A READ cursor (`<agent>.json`) indexes PARSED ENTRIES — a message count. A PUSH cursor
+      // (`<agent>.push.json`) is a BYTE OFFSET: `advancePushCursor` writes `toOffset ?? statSync(file).size`,
+      // "the byte just past the line that was delivered". Measuring a byte offset against a message
+      // count makes EVERY push cursor on a non-trivial inbox read as past EOF — and because this
+      // check is `fixable`, the "clamp" then rewinds it to the count. ⟨q-f018dd51⟩: on 2026-09-17 a
+      // `doctor {fix:true}` did exactly that to 11 of 13 seats across two fleets in one call —
+      // one coordinator seat went from byte 3,413,506 to byte 992, i.e. to the START of its inbox.
+      // Nothing replayed only because the running tails held an in-process high-water mark; the
+      // damage was LATENT and would have fired on the next restart, when that mark is gone.
+      const boundOf = async (file: string) => (kind === "push" ? await byteSizeOf(file) : (await countFor(file)).parsed);
+      const unit = kind === "push" ? "bytes" : "entries";
+      const inboxMax = await boundOf(inboxFile(id));
+      if ((cursor.inboxOffset ?? 0) > inboxMax) overflow.push(`inboxOffset ${cursor.inboxOffset}>${inboxMax} ${unit}`);
+      const roomMax = await boundOf(ROOM_FILE);
+      if ((cursor.roomOffset ?? 0) > roomMax) overflow.push(`roomOffset ${cursor.roomOffset}>${roomMax} ${unit}`);
+      const statusMax = await boundOf(STATUS_FILE);
+      if ((cursor.statusOffset ?? 0) > statusMax) overflow.push(`statusOffset ${cursor.statusOffset}>${statusMax} ${unit}`);
       for (const [chan, off] of Object.entries(cursor.roomOffsets ?? {})) {
-        const max = (await countFor(roomFile(chan))).parsed;
-        if (off > max) overflow.push(`roomOffsets[${chan}] ${off}>${max}`);
+        const max = await boundOf(roomFile(chan));
+        if (off > max) overflow.push(`roomOffsets[${chan}] ${off}>${max} ${unit}`);
+      }
+      // ⭐ THE DIRECTION THAT WAS NEVER TESTED, AND THE ONE THAT ACTUALLY BIT. Everything above asks
+      // "is the cursor PAST the end" — an over-run. A seat goes silently deaf from the opposite
+      // shape: its push cursor sits BEHIND a grown inbox, so mail is owed and never typed
+      // (⟨q-cdb5b007⟩). doctor reported "all cursor offsets are within bounds" for seats 10KB
+      // behind, all day, while a worker missed its GO and idled 40 minutes.
+      // ⛔ REPORTED, NEVER "FIXED": advancing a lagging cursor to EOF SKIPS the backlog rather than
+      // delivering it. The remedy is a working tail; a clamp here would destroy the evidence and
+      // the mail. This is why lag is deliberately absent from the `fix` branch below.
+      if (kind === "push") {
+        const size = await byteSizeOf(inboxFile(id));
+        const behind = size - Number(cursor.inboxOffset ?? 0);
+        if (behind > 0) lagging.push(`${id}: ${behind} byte(s) owed (push cursor ${cursor.inboxOffset ?? 0}/${size})`);
       }
       if (overflow.length) {
         broken.push(`${id}${kind === "push" ? " (push)" : ""}: ${overflow.join(", ")}`);
@@ -1669,7 +1705,9 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
             if ((c.statusOffset ?? 0) > statusMax) c.statusOffset = statusMax;
             if (c.roomOffsets) {
               for (const chan of Object.keys(c.roomOffsets)) {
-                const max = counts.get(roomFile(chan))?.parsed ?? 0;
+                // Same per-kind bound as the detection above — a clamp that used the other unit
+                // would be the very rewind this row exists to stop.
+                const max = kind === "push" ? (sizes.get(roomFile(chan)) ?? 0) : (counts.get(roomFile(chan))?.parsed ?? 0);
                 if (c.roomOffsets[chan] > max) c.roomOffsets[chan] = max;
               }
             }
@@ -1682,10 +1720,24 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     findings.push({
       check: "cursor-past-eof",
       level: broken.length ? "error" : "ok",
-      detail: broken.length ? `${broken.length} cursor(s) with an offset past EOF — delivery stalled` : "all cursor offsets are within bounds",
+      detail: broken.length
+        ? `${broken.length} cursor(s) with an offset past EOF — delivery stalled`
+        : "all cursor offsets are within bounds (push cursors measured in BYTES, read cursors in parsed entries)",
       fixable: true,
       items: broken.length ? broken : undefined,
     });
+    // A SEPARATE FINDING, AND DELIBERATELY `fixable: false`. Lag is the ⟨q-cdb5b007⟩ deafness shape:
+    // mail owed and never typed. It is a symptom of a tail that is not running or not typing, and
+    // the remedy is that tail — advancing the cursor would SKIP the backlog, not deliver it.
+    findings.push({
+      check: "push-cursor-lag",
+      level: lagging.length ? "warn" : "ok",
+      detail: lagging.length
+        ? `${lagging.length} seat(s) with mail owed but not yet typed into their pane — a tail that is not running, or running and holding. Check herdrTail: delivered/held tells you which, and they have opposite fixes. NOT auto-repairable: advancing a lagging cursor SKIPS the backlog instead of delivering it.`
+        : "no push cursor is behind its inbox",
+      fixable: false,
+      items: lagging.length ? lagging : undefined,
+    });
   }
 
   // 5. Malformed JSONL lines (silently desync offset math between server + hooks).