agent-coord-mcp 0.26.27 → 0.26.29

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();
@@ -117,6 +127,19 @@ export async function tailOnce(
   // read its marker file on every tick while the stated idle cost said otherwise.
   if (refresh) {
     ctx.marker = (opts.markerOf ?? readOwnMarker)(agentId);
+    // ⟨q-d58ccdce⟩ ⛔⛆⛆ THIS BRANCH IS THE WHOLE DEFECT. `marker.rooms === false` makes
+    // `ctx.rooms` PERMANENTLY EMPTY — every room this agent belongs to is silently excluded
+    // from `sources` below, so the per-source loop never runs for a single one of them. That
+    // is a total, structural skip with no `continue` to log: #395's per-outcome push logging
+    // fires only for a source the loop actually reaches, and a room that is never a source
+    // produces zero log lines forever — indistinguishable from a room with nothing owed.
+    // Measured live 2026-09-19: every groundwork-kit-* seat's marker had `rooms:false` (a
+    // side effect of `attach_agent {..., includeRoom:false}`, called believing it only
+    // affected DM liveness), while every unaffected control seat had `rooms:true`. So THIS
+    // is the log line the class needed — not one more line inside a loop that never starts.
+    if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms === false) {
+      log(`[herdr-tail] rooms DISABLED for ${agentId} — marker.rooms=false, so no room is ever tailed regardless of membership (⟨q-d58ccdce⟩); re-attach with includeRoom:true (or omit it) to restore room delivery`);
+    }
     if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms !== false) {
       try {
         const all = await (opts.roomsOf ?? getRooms)();
@@ -140,13 +163,20 @@ export async function tailOnce(
     // ⛔ FIRST SIGHT OF A SOURCE UNDER seedEof: adopt EOF and type NOTHING. This is the only place
     // the starting offset is decided, and it is decided EXPLICITLY rather than inherited from a
     // cursor file that a restart may have reset. Per source, so a room joined later seeds on its
-    // own first sight instead of replaying its history.
+    // own first sight instead of replaying its history. Logged (low-frequency: once per source
+    // per process) so a seat that never types into a newly-joined room is distinguishable from
+    // one that was never told the room existed.
     if (ctx.seedEof && !ctx.seeded.has(key)) {
       ctx.seeded.add(key);
       ctx.hw.set(key, size);
+      log(`[herdr-tail] seeded ${key} at EOF (${size} bytes) for ${agentId} — first sight this process, nothing predating the tail will be typed`);
       continue;
     }
     const from = await offsetOf(agentId, src, ctx);
+    // ⭐ NEGATIVE CONTROL FOR THE CLASS THIS ROW IS ABOUT: nothing is logged here when
+    // `size === from` — a source with nothing owed must stay silent, or every idle room on
+    // every tick becomes a line and the log that is supposed to make a real stall visible
+    // drowns in ones that are not.
     if (size <= from) continue;
 
     for (const { msg, end } of newMessagesIn(src.file, from)) {
@@ -155,6 +185,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

@@ -1668,7 +1668,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       // 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 —
-      // cass-poc-coordinator went from byte 3,413,506 to byte 992, i.e. to the START of its inbox.
+      // 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);

package/src/transports/config.ts

@@ -1,16 +1,21 @@
 /**
- * WHICH TRANSPORT THIS FLEET IS CONFIGURED TO USE (Phase 5.4 Task 3.1–3.2).
+ * WHICH TRANSPORT A SEAT ON THIS MACHINE IS CONFIGURED TO USE (Phase 5.4 Task 3.1–3.2).
  *
- * Whole-fleet, read ONCE at startup, per David 2026-09-11 — no per-seat
- * branching in `send_command` or `attach`. Memoised for that reason and not for
- * speed: a value that can be re-read mid-process is a value that can change
- * mid-process, and then two calls in one session disagree about what the fleet
- * is doing.
+ * ⟨q-d404a6f6⟩ THIS IS MACHINE-SCOPED, NOT FLEET-WIDE — the file lives at
+ * `$AGENT_COORD_DIR/config.json`, a path local to ONE box. A fleet now spans
+ * machines: `tmux-push-remote` exists precisely for a seat on another host, and
+ * that seat never reads THIS machine's config.json — it has (or lacks) its own.
+ * Calling this "the fleet's statement" was false and load-bearing: it read as
+ * an argument against ANY compiled default, when the argument that actually
+ * holds (below) is narrower — against a default picked HERE being assumed
+ * correct on a DIFFERENT machine. Per-process (read ONCE at startup, no
+ * per-seat branching in `send_command` or `attach` for the seats ON THIS BOX)
+ * is still exactly right; "whole-fleet" was the wrong word for it.
  *
  * ⛔ AN UNKNOWN VALUE REFUSES AT STARTUP. It does not fall back to anything.
  *
  * The reason is not tidiness. A SILENT FALLBACK AND A CORRECT DEFAULT PRODUCE
- * IDENTICAL EVIDENCE: both give you a fleet on some transport with nothing in any
+ * IDENTICAL EVIDENCE: both give you a seat on some transport with nothing in any
  * log, so a typo in the config reads exactly like a deliberate default, and the
  * person who typed `heardr` spends the afternoon asking why their transport
  * change did nothing. Refusing is louder than the bug it prevents.
@@ -20,7 +25,7 @@
  * removing the fallback would have meant every unconfigured session refused
  * with "unknown transport 'tmux-push'" — a config-file bug wearing a runtime
  * bug's clothes. Picking a new implicit default (herdr, say) would be correct
- * on THIS fleet today and wrong on the next machine that doesn't run herdr —
+ * on THIS machine today and wrong on the next one that doesn't run herdr —
  * the exact silent-guess failure ⟨q-e439e4ad⟩ spent a day fixing, moved one
  * layer up. So: zero configuration REFUSES, naming the kinds that exist.
  */
@@ -29,26 +34,27 @@ import path from "node:path";
 import { ROOT } from "../store.js";
 import { TRANSPORT_KINDS, type TransportKind } from "./types.js";
 
-/** `$AGENT_COORD_DIR/config.json`, the fleet-wide file. */
+/** `$AGENT_COORD_DIR/config.json` — MACHINE-scoped, not fleet-wide: see the file header. */
 export const TRANSPORT_CONFIG_FILE = path.join(ROOT, "config.json");
 export const TRANSPORT_ENV_VAR = "AGENT_COORD_TRANSPORT";
 
 /**
  * PRECEDENCE, documented here because 3.2 asks for a decision and not a
- * preference: **config file > env > default**.
+ * preference: **machine config file > env**. (⟨q-ec020f6a⟩: no default follows
+ * either — see the file header.)
  *
- * The file wins because it is the FLEET's statement and is reviewable — it sits
- * on disk where every seat reads the same bytes, and a wrong value can be
- * corrected in one place. An env var is per-process: it is the right tool for
- * one seat to deviate deliberately (a test, a bisect), and the wrong tool for
- * stating what the fleet does, because nothing can see it from outside that
- * process. So the narrower, less visible source loses to the broader one, and
- * `source` is reported so a surprising answer can be traced to its origin
- * rather than guessed at.
+ * The file wins because it is this MACHINE's statement and is reviewable — it
+ * sits on disk where every seat ON THIS BOX reads the same bytes, and a wrong
+ * value can be corrected in one place. An env var is per-process: it is the
+ * right tool for one seat to deviate deliberately (a test, a bisect), and the
+ * wrong tool for stating what this machine's seats do by default, because
+ * nothing can see it from outside that process. So the narrower, less visible
+ * source loses to the broader one, and `source` is reported so a surprising
+ * answer can be traced to its origin rather than guessed at.
  */
 export type ConfiguredTransport = {
   kind: TransportKind;
-  source: "config" | "env";
+  source: "machine-config" | "env";
   /** Where the value came from, for an error message a human can act on. */
   origin: string;
 };
@@ -73,12 +79,38 @@ function asKind(value: unknown, origin: string): TransportKind {
 let cached: ConfiguredTransport | undefined;
 
 /**
- * Resolve the fleet's transport. Throws on an unknown value — call it once at
+ * ⭐ ⟨q-9e0072b3⟩ THE PRECEDENCE DECISION, PULLED OUT SO IT CAN BE CALLED WITHOUT TOUCHING
+ * DISK OR `process.env`. `configuredTransport()` below is the only caller that supplies real
+ * values read from THIS machine; anything else — a test, or a capability probe that must prove
+ * a property of the CODE rather than a fact about one machine's config.json — can hand this
+ * CONSTRUCTED values instead. That is what makes it possible to probe "does the machine-config/
+ * env vocabulary exist and resolve correctly" without the probe itself becoming an undeclared
+ * read of a mutable, machine-local baseline (`check-baseline-declared` correctly caught the
+ * first version of that probe calling `configuredTransport()` directly for exactly this reason).
+ */
+export function resolveConfiguredTransport(input: { fileHasTransport: boolean; fileTransport: unknown; env: string | undefined }): ConfiguredTransport {
+  if (input.fileHasTransport) {
+    return { kind: asKind(input.fileTransport, `${TRANSPORT_CONFIG_FILE} ("transport")`), source: "machine-config", origin: TRANSPORT_CONFIG_FILE };
+  }
+  if (input.env !== undefined && input.env !== "") {
+    return { kind: asKind(input.env, `$${TRANSPORT_ENV_VAR}`), source: "env", origin: `$${TRANSPORT_ENV_VAR}` };
+  }
+  throw new Error(
+    `[agent-coord-mcp] no transport configured — set $${TRANSPORT_ENV_VAR} or ${TRANSPORT_CONFIG_FILE} ` +
+      `("transport") to one of: ${TRANSPORT_KINDS.join(", ")}. ` +
+      `REFUSING rather than picking one: a default that is right for this machine today is wrong for the ` +
+      `next one that doesn't have it, and the two failures leave identical evidence.`,
+  );
+}
+
+/**
+ * Resolve THIS MACHINE's configured transport. Throws on an unknown value — call it once at
  * startup so the refusal lands before any agent attaches.
  */
 export function configuredTransport(): ConfiguredTransport {
   if (cached) return cached;
 
+  let fileTransport: unknown;
   if (existsSync(TRANSPORT_CONFIG_FILE)) {
     let parsed: unknown;
     try {
@@ -90,28 +122,14 @@ export function configuredTransport(): ConfiguredTransport {
       throw new Error(
         `[agent-coord-mcp] ${TRANSPORT_CONFIG_FILE} is unreadable (${(e as Error).message}). ` +
           `REFUSING rather than treating it as absent: a file that exists and cannot be read is not the ` +
-          `same as no file, and defaulting here would hide a stated intent behind a working fleet.`,
+          `same as no file, and defaulting here would hide a stated intent behind a seat that looked healthy.`,
       );
     }
-    const raw = (parsed as { transport?: unknown } | null)?.transport;
-    if (raw !== undefined) {
-      cached = { kind: asKind(raw, `${TRANSPORT_CONFIG_FILE} ("transport")`), source: "config", origin: TRANSPORT_CONFIG_FILE };
-      return cached;
-    }
-  }
-
-  const env = process.env[TRANSPORT_ENV_VAR];
-  if (env !== undefined && env !== "") {
-    cached = { kind: asKind(env, `$${TRANSPORT_ENV_VAR}`), source: "env", origin: `$${TRANSPORT_ENV_VAR}` };
-    return cached;
+    fileTransport = (parsed as { transport?: unknown } | null)?.transport;
   }
 
-  throw new Error(
-    `[agent-coord-mcp] no transport configured — set $${TRANSPORT_ENV_VAR} or ${TRANSPORT_CONFIG_FILE} ` +
-      `("transport") to one of: ${TRANSPORT_KINDS.join(", ")}. ` +
-      `REFUSING rather than picking one: a default that is right for this fleet today is wrong for the ` +
-      `next machine that doesn't have it, and the two failures leave identical evidence.`,
-  );
+  cached = resolveConfiguredTransport({ fileHasTransport: fileTransport !== undefined, fileTransport, env: process.env[TRANSPORT_ENV_VAR] });
+  return cached;
 }
 
 /**

package/src/transports/herdr.ts

@@ -136,7 +136,13 @@ const LIVE_STATUSES = new Set(["idle", "working", "blocked", "done"]);
  *   held              — NO key was sent (no ready box, a draft, a menu, or the pane unreadable).
  *                       Safe to retry.
  *   typed-unconfirmed — the text was typed but did not show in the box; Enter was NOT sent.
- *   pending           — the text is still in the box after every Enter.
+ *   pending           — the text is still in the box after every Enter. ⟨q-1ce5bc97⟩ step 1: this
+ *                       is the MOST recoverable non-delivery there is — the payload is KNOWN to be
+ *                       sitting, verified, in the target's own box, not lost and not ambiguous.
+ *                       `safeToRetry: false` here turned a transient misread into a PERMANENT drop:
+ *                       the tail's held-path (`herdr-tail.ts`) is what retries safely (it advances
+ *                       nothing on a hold, and stops the source rather than typing past it), so
+ *                       refusing that path was refusing the one recovery this outcome has. NOW true.
  *   unverified        — Enter was sent and the screen after it does not prove submission.
  */
 export type PushOutcome = "delivered" | "held" | "typed-unconfirmed" | "pending" | "unverified";
@@ -164,8 +170,28 @@ export type HerdrTransportOptions = {
    * variable at a time, six others left in place — was what turned it green.
    */
   env?: Record<string, string | undefined>;
+  /** Override the submit mode this instance uses; defaults to `submitModeOf(this.#env)`. Tests only. */
+  submitMode?: SubmitMode;
 };
 
+/**
+ * ⟨q-f7e3c701⟩ — WHICH SUBMIT PATH `push` USES. `agent-prompt` is the atomic fix
+ * (`herdr agent prompt <target> <text>`, one call, no type→read-back→Enter window). `send-keys`
+ * is today's path (type, verify it landed, Enter, verify it submitted).
+ *
+ * DEFAULT IS `send-keys`, DELIBERATELY. The blast radius of switching is both fleets and the
+ * failure mode is silence — a wrong default ships broken delivery to every seat with no signal
+ * until someone notices nothing arrived. `agent-prompt` is enabled per-seat as a canary via
+ * `AGENT_COORD_SUBMIT=agent-prompt`, compared against control seats by `outcome=` rate in
+ * bus-daemon.err.log, and reverted by unsetting the variable — no republish required, which
+ * matters because 0.26.28 took two days to travel merged→observed.
+ */
+export type SubmitMode = "agent-prompt" | "send-keys";
+export const SUBMIT_MODE_ENV_VAR = "AGENT_COORD_SUBMIT";
+export function submitModeOf(env: Record<string, string | undefined> = process.env): SubmitMode {
+  return env[SUBMIT_MODE_ENV_VAR] === "agent-prompt" ? "agent-prompt" : "send-keys";
+}
+
 /**
  * ⟨q-abd88dd4⟩ — THE PID A HERDR MARKER CARRIES, chosen for the readers that CANNOT be patched.
  *
@@ -219,6 +245,7 @@ export class HerdrTransport implements Transport {
   #readLines: number;
   #markerPid: () => HerdrMarkerPid;
   #env: Record<string, string | undefined>;
+  #submitMode: SubmitMode;
 
   constructor(opts: HerdrTransportOptions = {}) {
     this.#run = opts.run ?? defaultHerdrRunner;
@@ -231,6 +258,7 @@ export class HerdrTransport implements Transport {
     this.#readLines = opts.readLines ?? 40;
     this.#markerPid = opts.markerPid ?? (() => herdrMarkerPid());
     this.#env = opts.env ?? process.env;
+    this.#submitMode = opts.submitMode ?? submitModeOf(this.#env);
   }
 
   /** Is herdr on this host AND is its server running? Both, or the reason. */
@@ -324,6 +352,9 @@ export class HerdrTransport implements Transport {
     if (!avail.available) return { delivered: false, outcome: "held", safeToRetry: true, error: avail.reason };
     const target = targetOf(marker);
     if (!target) return { delivered: false, outcome: "held", safeToRetry: true, error: "no target recorded on the marker" };
+    // ⟨q-f7e3c701⟩ ATOMIC SUBMIT, canaried per seat via AGENT_COORD_SUBMIT. Everything below this
+    // branch is the send-keys path (today's default); #pushAgentPrompt is the opt-in replacement.
+    if (this.#submitMode === "agent-prompt") return this.#pushAgentPrompt(target, text);
     const payload = opts.paste === false ? text : `${PASTE_START}${neutralizeControls(text)}${PASTE_END}`;
     const enterKey = herdrKeyName("enter");
     if (!enterKey.ok) return { delivered: false, outcome: "held", safeToRetry: true, error: enterKey.error };
@@ -354,7 +385,74 @@ export class HerdrTransport implements Transport {
       if (boxHoldsPayload(box, text)) continue;
       return { delivered: false, verified: false, outcome: "unverified", safeToRetry: false, enters, error: `enter sent to ${target}, but the screen after it does not show the message submitted (${box.ready ? (box.draft ? "the box holds other text" : "the box is empty and the transcript gained no line carrying it") : box.reason})` };
     }
-    return { delivered: false, verified: true, outcome: "pending", safeToRetry: false, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+    return { delivered: false, verified: true, outcome: "pending", safeToRetry: true, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+  }
+
+  /**
+   * ⟨q-f7e3c701⟩ ATOMIC SUBMIT, behind `AGENT_COORD_SUBMIT=agent-prompt` (default `send-keys` —
+   * see `submitModeOf`). `herdr agent prompt <target> <text> --wait --until working` types and
+   * submits in ONE call: no type→read-back→Enter window for a decoration to land in, which is
+   * the class the send-keys path above exists to survive. MEASURED (joint cross-fleet design,
+   * 2026-09-21): 4/4 across two hosts, including a LIVE WEDGE the send-keys path had already
+   * abandoned in the same minute.
+   *
+   * ⛔ `refusalBeforeKeys` IS NOT OPTIONAL — MEASURED ON A THROWAWAY PANE: `agent prompt` into a
+   * DIRTY composer returned `agent_prompted` (success) and CONCATENATED the stale draft with the
+   * new text, no separator, then submitted both. Atomic submit alone is strictly WORSE than
+   * today: a recoverable `held` becomes unrecoverable corruption carrying a success receipt.
+   * `agent_blocked` is a STATUS axis and is BLIND to a dirty composer (reads
+   * `status: idle · interactive_ready: true` regardless), so it cannot substitute for reading
+   * the box first — this method still reads it, exactly as the send-keys path does.
+   *
+   * Receipt is `--until working`, an OBSERVED state transition — strictly stronger than "I typed
+   * it and could read it back", the only receipt class send-keys has ever had. A stall/timeout is
+   * treated as UNCONFIRMED, never as safe to retry: unlike send-keys's `typed-unconfirmed` (where
+   * nothing had actually been typed yet), a stalled atomic submit may already have gone through,
+   * and retrying risks a genuine double-send.
+   *
+   * ⛔⛔ THE FIELD PATH BELOW WAS WRONG ONCE, SHIPPED, AND CAUGHT BY QA'S OWN LIVE SMOKE TEST
+   * BEFORE MERGE — recorded because the wrong version passed every unit test, having been
+   * written against a GUESSED shape (`json.status ?? json.result.status`) that the mocks then
+   * reproduced instead of measuring. Against the real CLI that path is always `undefined`, so
+   * every genuine success fell through to the catch-all and the feature would have reported
+   * 100% failure on real hardware. VERIFIED PAYLOADS, captured against herdr 0.9.1 by the aide
+   * and independently reproduced here on a disposable scratch pane (`herdr workspace create` /
+   * `agent start --kind claude` / closed after):
+   *   success:  {"result":{"agent":{...},"type":"agent_prompted"}}   — result.type, not result.status
+   *   blocked:  {"error":{"code":"agent_blocked","message":"..."}}   — TOP-LEVEL error, no `result` at all
+   *   timeout:  {"error":{"code":"timeout","message":"..."}}         — same top-level shape as blocked
+   * So this is TWO PATHS, not one field read: `result.type` for success, `error.code` for every
+   * refusal. A single-location parse mishandles one of them regardless of which is picked — the
+   * exact shape of the bug that shipped. `agent_prompt_stalled` was NOT reproduced against a real
+   * binary despite attempting it (the 5000ms stall window did not fire in either kit's or my own
+   * attempts) — it is handled via the same `error.code` path as `agent_blocked`/`timeout` BY
+   * ANALOGY with the CLI's consistent refuse-via-top-level-error convention, not by measurement.
+   * If that analogy is wrong, the failure mode is `unverified/safeToRetry:false` (never a
+   * double-send) rather than a false "delivered", so the untested case fails safe.
+   */
+  async #pushAgentPrompt(target: string, text: string): Promise<HerdrPushResult> {
+    if (readyProfile().profile !== "none") {
+      const before = readReadyBox(this.#screen(target));
+      const refusal = refusalBeforeKeys(before);
+      if (refusal) return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `held, nothing typed into ${target}: ${refusal}` };
+    }
+    const r = this.#run(["agent", "prompt", target, text, "--wait", "--until", "working"]);
+    const resultType = (r.json as { result?: { type?: string } } | undefined)?.result?.type;
+    if (r.ok && resultType === "agent_prompted") {
+      return { delivered: true, verified: true, outcome: "delivered", safeToRetry: false };
+    }
+    if (r.error?.code === "agent_blocked") {
+      // MEASURED: nothing is typed into the pane on agent_blocked — the agent itself refused the
+      // prompt before any input was sent. Safe to retry, same as a send-keys `held`.
+      return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `agent_blocked at ${target}: ${r.error.message}` };
+    }
+    if (r.error?.code === "agent_prompt_stalled" || r.error?.code === "timeout") {
+      return {
+        delivered: false, verified: false, outcome: "unverified", safeToRetry: false,
+        error: `${r.error.code} at ${target}: submission unconfirmed by --wait --until working — not retried, to avoid a double-send on an atomic path`,
+      };
+    }
+    return { delivered: false, verified: false, outcome: "unverified", safeToRetry: false, error: `agent prompt to ${target} refused or unrecognised: ${r.error?.message ?? r.stderr ?? JSON.stringify(r.json)}` };
   }
 
   /** The screen, styled, so the ready-box reader can tell a ghost suggestion from a draft. null = unreadable. */
@@ -380,7 +478,7 @@ export class HerdrTransport implements Transport {
       if (pending === false) return { delivered: true, verified: true, unguarded: true, outcome: "delivered", safeToRetry: false, enters };
       if (pending === null) return { delivered: false, verified: false, unguarded: true, outcome: "unverified", safeToRetry: false, enters, error: `enter sent to ${target}, but the pane could not be read back to verify it` };
     }
-    return { delivered: false, verified: true, unguarded: true, outcome: "pending", safeToRetry: false, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+    return { delivered: false, verified: true, unguarded: true, outcome: "pending", safeToRetry: true, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
   }
 
   /**

package/src/transports/index.ts

@@ -14,7 +14,7 @@ import { configuredTransport } from "./config.js";
 export * from "./types.js";
 export * from "./config.js";
 export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
-export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, herdrMarkerPid, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult, type HerdrMarkerPid } from "./herdr.js";
+export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, herdrMarkerPid, submitModeOf, SUBMIT_MODE_ENV_VAR, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult, type HerdrMarkerPid, type SubmitMode } from "./herdr.js";
 
 let host: TmuxHost | undefined;