agent-coord-mcp 0.26.26 → 0.26.28

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";
@@ -354,7 +360,7 @@ 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` };
   }
 
   /** The screen, styled, so the ready-box reader can tell a ghost suggestion from a draft. null = unreadable. */
@@ -380,7 +386,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` };
   }
 
   /**