agent-coord-mcp 0.26.19 → 0.26.20

package/src/tools/transport.ts

@@ -1,4 +1,16 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+import {
+  TMUX_PUSH,
+  registerTmuxHost,
+  type TmuxHost,
+  isLocallyProbeable,
+  isTmuxKind,
+  paneExists,
+  probePane,
+  tmuxVersion,
+  targetOf,
+  tmuxAvailable,
+} from "../transports/index.js";
 import { newestMtimeUnder, onDiskBuildMtime, onDiskSourceMtime, SERVER_BUILD_MTIME, SERVER_BUILD_SHA, BUILD_DIR } from "../build.js";
 import { prefixOf, prefixVerdict } from "../prefix.js";
 import { execFileSync } from "node:child_process";
@@ -119,17 +131,11 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   let paneAlive: boolean | undefined;
   if (marker) {
     transportLive = isMarkerLive(marker, reg, now);
-    if (transportLive && marker.transport === "tmux-push" && marker.tmuxTarget) {
+    if (transportLive && isLocallyProbeable(marker.transport) && targetOf(marker)) {
       // The pusher can outlive its pane (agent window closed) — probe the pane.
-      // `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-      // DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-      // ago, so the probe had ZERO discriminating power and reported every dead
-      // pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-      // tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-      // Positive control, both directions: bogus target -> has-session exit 1,
-      // display-message exit 0; live pane -> both exit 0.
-      const probe = spawnSync("tmux", ["has-session", "-t", marker.tmuxTarget]);
-      paneAlive = probe.status === 0;
+      // Why `has-session` and not `display-message`, with the positive control
+      // both ways, is documented once on `paneExists`.
+      paneAlive = paneExists(targetOf(marker)!);
     }
   }
 
@@ -146,7 +152,7 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   // same shape as `stall_clock_status` before Task 13.1. A REMOTE pusher, or
   // an agent with no probeable marker at all, has no pid to fall back on —
   // there heartbeat genuinely IS the liveness mechanism, unchanged.
-  const heartbeatIsValidSignal = !marker || marker.transport !== "tmux-push";
+  const heartbeatIsValidSignal = !marker || !isLocallyProbeable(marker.transport);
   const alive = reachable || (heartbeatIsValidSignal && heartbeatFresh);
 
   let echoSent = false;
@@ -196,7 +202,7 @@ export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
 // Transports whose pusher can actually TYPE a slash command into a live CLI.
 // A control command is meaningless to a plain MCP poller, so send_command is
 // gated to agents currently attached over one of these.
-const TMUX_TRANSPORTS = new Set(["tmux-push", "tmux-push-remote"]);
+
 
 // Normalize "clear" / "/clear" / "  /Clear " → "clear"; null if not allowlisted.
 function normalizeControlCommand(raw: string): string | null {
@@ -208,7 +214,7 @@ function normalizeControlCommand(raw: string): string | null {
 async function liveTmuxTargets(): Promise<Map<string, TransportMarker>> {
   const all = await loadLiveTransports();
   const out = new Map<string, TransportMarker>();
-  for (const [id, m] of all) if (TMUX_TRANSPORTS.has(m.transport)) out.set(id, m);
+  for (const [id, m] of all) if (isTmuxKind(m.transport)) out.set(id, m);
   return out;
 }
 
@@ -645,19 +651,13 @@ export async function attachAgentTool(args: {
     };
   }
 
-  // Validate target exists.
-  // `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-  // DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-  // ago, so the probe had ZERO discriminating power and reported every dead
-  // pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-  // tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-  // Positive control, both directions: bogus target -> has-session exit 1,
-  // display-message exit 0; live pane -> both exit 0.
-  const probe = spawnSync("tmux", ["has-session", "-t", target]);
-  if (probe.status !== 0) {
+  // Validate target exists. The probe's discriminating power, and the control
+  // that proves it, are documented once on `paneExists`.
+  const targetProbe = probePane(target);
+  if (!targetProbe.exists) {
     return {
       ok: false,
-      error: `tmux target '${target}' not found: ${(probe.stderr ?? "").toString().trim()}`,
+      error: `tmux target '${target}' not found: ${targetProbe.stderr}`,
     };
   }
 
@@ -723,8 +723,14 @@ export async function attachAgentTool(args: {
   const scriptMtime = newestPusherSourceMtime();
   const marker: TransportMarker = {
     agentId: args.agentId,
-    transport: "tmux-push",
+    transport: TMUX_PUSH,
     pid,
+    // DUAL-WRITTEN, and the duplication is the point. `target` is what every
+    // consumer now reads (`targetOf`); `tmuxTarget` is what the code a merge
+    // revert restores reads. Writing only the new field would leave markers the
+    // old server cannot parse, and that failure does not degrade gracefully —
+    // it silences every attached lane at once.
+    target,
     tmuxTarget: target,
     since: Date.now(),
     scriptMtime,
@@ -749,7 +755,7 @@ export async function attachAgentTool(args: {
   return {
     ok: true,
     agentId: args.agentId,
-    transport: "tmux-push",
+    transport: TMUX_PUSH,
     tmuxTarget: target,
     pid,
     log,
@@ -1171,6 +1177,53 @@ async function scanStaleLocks(olderThanMs: number, now: number): Promise<{ path:
   return out;
 }
 
+/* ── wiring the seam's TMUX HOST (Phase 5.4 Task 3) ─────────────────────────── */
+
+/**
+ * The process-layer half of `TmuxTransport`, supplied by the module that owns
+ * pusher spawn, receipts and marker files.
+ *
+ * ⚠ SCOPE, STATED RATHER THAN IMPLIED: Task 3 puts the seam in the IDENTITY and
+ * DIAGNOSIS path — `capabilities` asks the live transport what it is, and the
+ * mixed-fleet check reads markers through it. DELIVERY STILL RUNS THROUGH THE
+ * EXISTING CODE PATHS. Task 2's gate was that nothing changes, and rerouting
+ * every push through a new object would change the thing most likely to break
+ * quietly. So the four delivery methods below THROW rather than no-op: a host
+ * that silently accepted a push and dropped it would be the one failure this
+ * fleet cannot observe, and an explicit throw is reachable only from code that
+ * has not been written yet.
+ */
+const TMUX_HOST: TmuxHost = {
+  attach: async () => {
+    throw new Error("TmuxTransport.attach is not the delivery path yet — call attachAgentTool (Phase 5.4 Task 3 wires identity only)");
+  },
+  detach: async () => {
+    throw new Error("TmuxTransport.detach is not the delivery path yet — call detachAgentTool");
+  },
+  push: async () => {
+    throw new Error("TmuxTransport.push is not the delivery path yet — delivery runs through the pusher process");
+  },
+  sendControl: async () => {
+    throw new Error("TmuxTransport.sendControl is not the delivery path yet — call sendCommandTool");
+  },
+  /**
+   * Is the pusher behind this marker still running? Reuses `isPusherProcess`,
+   * which checks the COMMAND of the pid rather than merely that a pid exists —
+   * a recycled pid belonging to something else is not a live pusher.
+   */
+  pusherAlive: (marker) => isPusherProcess(marker.pid),
+  killPusher: (marker) => {
+    try {
+      process.kill(marker.pid, "SIGTERM");
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+registerTmuxHost(TMUX_HOST);
+
 export const doctorSchema = {
   fix: z.boolean().optional(),
   maxFileBytes: z.number().int().positive().optional(),
@@ -1231,7 +1284,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (!isLocallyProbeable(marker.transport)) continue; // remote = can't verify (documented limit: can't stat another host)
       if (marker.scriptMtime === undefined) {
         // ABSENCE IS NOT EXEMPTION. The field's own writer once dropped it,
         // and the silent skip here meant the check was disabled by the very
@@ -1339,7 +1392,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (!isLocallyProbeable(marker.transport)) continue; // remote = can't verify (documented limit: can't stat another host)
       if (marker.serverBuildMtime === undefined) {
         // ABSENCE IS NOT EXEMPTION — flipped in the same commit as the
         // scriptMtime absence above, so the two checks can never disagree
@@ -1434,7 +1487,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote: the script lives on another host
+      if (!isLocallyProbeable(marker.transport)) continue; // remote: the script lives on another host
       const { scriptMtime, serverBuildMtime, agentId } = marker;
       if (scriptMtime === undefined || serverBuildMtime === undefined || onDiskScript === undefined || onDiskServer === undefined) {
         // A pane missing either stamp cannot be classified. Saying so is the
@@ -1475,20 +1528,20 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   {
     // Without a tmux binary we can't tell "wedged" from "can't probe" — skip
     // rather than flag every local marker as dead.
-    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
+    const tmuxIsAvailable = tmuxAvailable();
     const wedged: { agentId: string; pid: number; file: string; target: string; isPusher: boolean }[] = [];
-    if (tmuxAvailable) {
+    if (tmuxIsAvailable) {
       for (const fname of await listTransportFiles()) {
         const file = path.join(TRANSPORT_DIR, fname);
         const marker = await readJson<TransportMarker | null>(file, null);
         if (!marker || !isMarkerLive(marker, reg, now)) continue;
-        if (marker.transport !== "tmux-push") continue; // remote = no local pane to probe
+        if (!isLocallyProbeable(marker.transport)) continue; // remote = no local pane to probe
         if (!marker.tmuxTarget) continue; // no target recorded, can't probe
         // has-session actually validates the target and fails on a dead
         // pane/session; `display-message -p -t <target> <literal>` does NOT
         // (tmux 3.6b exits 0 for any target, even a just-killed one, when
         // the format string has no #{...} needing that target resolved).
-        const probe = spawnSync("tmux", ["has-session", "-t", marker.tmuxTarget]);
+        const probe = { status: paneExists(targetOf(marker)!) ? 0 : 1 };
         if (probe.status === 0) continue; // pane alive
         // The marker's pid being alive does not make it OUR pid — see
         // isPusherProcess. Record the verdict now so `fix` only ever signals
@@ -1523,7 +1576,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       level: wedged.length ? "warn" : "ok",
       detail: wedged.length
         ? `${wedged.length} local pusher(s) alive (pid) but their tmux pane is gone — looks attached, delivers nothing. ${fix ? "Reaped (SIGTERM + marker cleared)." : "Run doctor with fix:true to SIGTERM and clear the marker."}`
-        : tmuxAvailable
+        : tmuxIsAvailable
           ? "no wedged local pushers (pid-alive, pane-dead)"
           : "tmux not available — skipped wedged-pusher pane probe",
       fixable: true,
@@ -1768,9 +1821,8 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     // Without a tmux binary we cannot probe a pane at all — every stale
     // agent is reported as an orphan candidate rather than silently split,
     // same posture `wedged-local-pushers` takes.
-    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
-    const paneAlive = (target: string): boolean =>
-      tmuxAvailable && spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+    const tmuxIsAvailable = tmuxAvailable();
+    const paneAlive = (target: string): boolean => tmuxIsAvailable && paneExists(target);
 
     const paneConfirmed: string[] = [];
     const orphans: string[] = [];
@@ -1779,8 +1831,9 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       if (now - a.lastHeartbeat <= EVICT_MS) continue;
       const age = `${Math.floor((now - a.lastHeartbeat) / 3600000)}h`;
       const marker = markerByAgent.get(id);
-      if (marker?.transport === "tmux-push" && marker.tmuxTarget && paneAlive(marker.tmuxTarget)) {
-        paneConfirmed.push(`${id} (${age}, pane '${marker.tmuxTarget}' still current)`);
+      const markerTarget = marker ? targetOf(marker) : undefined;
+      if (isLocallyProbeable(marker?.transport) && markerTarget && paneAlive(markerTarget)) {
+        paneConfirmed.push(`${id} (${age}, pane '${markerTarget}' still current)`);
       } else {
         orphans.push(`${id} (${age})`);
       }
@@ -1808,7 +1861,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       level: orphans.length ? "warn" : "ok",
       detail: orphans.length
         ? `${orphans.length} stale agent(s) have no live tmux pane behind them — permanent, will not clear on their own (unregister or let eviction drop them)`
-        : tmuxAvailable
+        : tmuxIsAvailable
           ? `no orphans among ${stale.length} stale agent(s)${stale.length ? " — all pane-confirmed current" : ""}`
           : "tmux not available — could not distinguish orphans from pane-confirmed stale agents",
       fixable: false,
@@ -2026,8 +2079,8 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   // identity is walk-up-to-.git + rev-parse (kit monorepo root); omitted
   // entirely when there is no checkout — never invented.
   {
-    const tmuxProbe = spawnSync("tmux", ["-V"]);
-    const tmuxOk = tmuxProbe.status === 0;
+    const tmuxReported = tmuxVersion();
+    const tmuxOk = tmuxReported !== undefined;
     const ident = resolveServerIdentity();
     const loc = ident.branch && ident.sha
       ? `path=${ident.path} version=${ident.version} ${ident.branch}@${ident.sha.slice(0, 12)}`
@@ -2045,7 +2098,7 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
       check: "environment",
       level: tmuxOk ? "ok" : "warn",
       detail: tmuxOk
-        ? `root=${ROOT}; node=${process.execPath}; ${loc}; tmux=${(tmuxProbe.stdout ?? "").toString().trim() || "present"}`
+        ? `root=${ROOT}; node=${process.execPath}; ${loc}; tmux=${tmuxReported || "present"}`
         : `root=${ROOT}; node=${process.execPath}; ${loc}; tmux NOT on PATH — the tmux-push transport will not work`,
       fixable: false,
       items,

package/src/tools/work.ts

@@ -139,8 +139,21 @@ function importedSummary(d: StoredDoc) {
     board: ["board"],
     legacy: ["queue", "done"],
   } as const;
+  // THE AXIS IS PASSED, NOT JUST ITERATED. It was already in scope here and was
+  // not handed to the predicate, so seam 0.1.16's queue-axis fix (#234) changed
+  // nothing any caller could observe: a pruned-but-healthy QUEUE.md kept
+  // reporting `unparsed: ["queue"]` because the predicate fell back to measuring
+  // authored CONTENT, and a queue keeps its headings and prose by design.
+  //
+  // Without the argument the queue axis asks "is there any prose here?" — which
+  // on a queue document is always yes. With it, it asks "did somebody write a
+  // ROW that failed to parse?", which is the question the zero actually needs.
+  // Every axis is passed its own name; only "queue" is treated differently
+  // inside the predicate. `done` and `board` keep the content measure
+  // deliberately — prose under an empty done log IS a fair reason to doubt that
+  // zero — so this is a narrowing of one axis, not a relaxation of all three.
   const unparsed = (AXES_BY_KIND[d.kind] as readonly (keyof typeof counts)[]).filter((axis) =>
-    zeroIsUnparsed(counts[axis], d.source),
+    zeroIsUnparsed(counts[axis], d.source, axis),
   );
   return {
     path: d.path,
@@ -188,6 +201,41 @@ async function loadState(project: string): Promise<WorkState | null> {
   return readJson<WorkState | null>(workFile(project), null);
 }
 
+/**
+ * WHICH STORED DOCS HAVE BEEN OVERTAKEN BY THE FILE ON DISK.
+ *
+ * THE FRESHNESS OF A RESPONSE IS THE FRESHNESS OF ITS STALEST FIELD, and before
+ * this the store was trusted because it existed. Measured on this fleet: a store
+ * imported at 17:29 already disagreed with 3 of its 4 documents by 17:42 —
+ * **thirteen minutes.** On a bus where several seats write coordination docs, the
+ * staleness window is minutes, not the weeks a dated store suggests.
+ *
+ * The instrument is mtime, and its limit is stated rather than hidden: an edit
+ * that PRESERVES mtime is not detected. mtime is used because the cheap question
+ * ("might the store be stale?") must not cost a full re-read of ~800KB of
+ * documents on every call; when the answer is yes, the re-read happens anyway.
+ * A missing file counts as stale — it cannot be compared, and "could not check"
+ * is not "checked and clean".
+ */
+async function staleDocs(state: WorkState): Promise<{ path: string; why: string }[]> {
+  const out: { path: string; why: string }[] = [];
+  for (const d of state.docs) {
+    const full = path.join(state.repo, d.path);
+    try {
+      const st = await fsp.stat(full);
+      if (st.mtimeMs > state.importedAt) {
+        out.push({
+          path: d.path,
+          why: `modified ${new Date(st.mtimeMs).toISOString()}, after the store was imported at ${new Date(state.importedAt).toISOString()}`,
+        });
+      }
+    } catch (e) {
+      out.push({ path: d.path, why: `cannot be read (${(e as Error).message}) — unverifiable, not assumed clean` });
+    }
+  }
+  return out;
+}
+
 async function saveState(state: WorkState): Promise<void> {
   await fsp.mkdir(WORK_DIR, { recursive: true });
   await fsp.writeFile(workFile(state.project), JSON.stringify(state, null, 2) + "\n", "utf8");
@@ -293,6 +341,13 @@ export async function listWorkTool(args: {
   // rather than in a comment.
   let state = await loadState(args.project);
   let source: "store" | "markdown" = "store";
+  // A STALE STORE IS NEVER SERVED SILENTLY. `staleStore` is present in the
+  // response whenever the store lost a race with the documents, so the caller
+  // learns it from the ANSWER rather than from a `source` field they would have
+  // to know to check. The confound this removes: `issues` carried live-looking
+  // diagnostics beside a stale queue, so the field that made a careful reader
+  // trust the payload was the one field that was current.
+  let staleStore: { reparsed: boolean; docs: { path: string; why: string }[]; note: string } | undefined;
   if (!state) {
     const imported = await importFromDisk(args.project, args.repo ?? process.cwd());
     if (!imported) {
@@ -300,6 +355,33 @@ export async function listWorkTool(args: {
     }
     state = imported;
     source = "markdown";
+  } else {
+    const stale = await staleDocs(state);
+    if (stale.length) {
+      const fresh = await importFromDisk(state.project, state.repo);
+      if (fresh) {
+        state = fresh;
+        source = "markdown";
+        staleStore = {
+          reparsed: true,
+          docs: stale,
+          note:
+            `the store was older than ${stale.length} of its document(s) and was NOT used — these rows were re-parsed from disk. ` +
+            `Every field below therefore shares one provenance.`,
+        };
+      } else {
+        // Cannot re-read, so the stale store is all there is. It is still
+        // reported, because an answer that cannot be refreshed is the one most
+        // in need of saying so.
+        staleStore = {
+          reparsed: false,
+          docs: stale,
+          note:
+            `the store is older than ${stale.length} of its document(s) and could NOT be re-parsed from disk — ` +
+            `the rows below are as stale as the store and must not be read as current.`,
+        };
+      }
+    }
   }
 
   const queue: QueueItem[] = [];
@@ -325,9 +407,9 @@ export async function listWorkTool(args: {
   // the caller does not have to know which kind its own id belongs to.
   if (args.id !== undefined) {
     const queueHit = queue.find((q) => q.id === args.id);
-    if (queueHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "queue" as const, item: queueHit };
+    if (queueHit) return { ok: true as const, project: state.project, repo: state.repo, source, ...(staleStore ? { staleStore } : {}), kind: "queue" as const, item: queueHit };
     const doneHit = done.find((d) => d.id === args.id);
-    if (doneHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "done" as const, item: doneHit };
+    if (doneHit) return { ok: true as const, project: state.project, repo: state.repo, source, ...(staleStore ? { staleStore } : {}), kind: "done" as const, item: doneHit };
     return { ok: false as const, error: `no queue item or DONE entry with id '${args.id}' in project '${state.project}'` };
   }
 
@@ -339,6 +421,16 @@ export async function listWorkTool(args: {
     project: state.project,
     repo: state.repo,
     source,
+    ...(staleStore ? { staleStore } : {}),
+    // PROVENANCE OF THE WHOLE PAYLOAD, including the instrument and its limit.
+    // Done-def 4: if any field can outpace another, the response says so rather
+    // than a comment saying it.
+    freshness: {
+      source,
+      importedAt: new Date(state.importedAt).toISOString(),
+      checkedAgainst: "file mtime vs store importedAt",
+      limit: "an edit that preserves mtime is not detected; a re-parse is triggered only when mtime is newer",
+    },
     // IDENTITY ONLY (Task 15.1) — id, priority, a bounded headline, and
     // blocked-by; never the full item text. Call again with `id` for one
     // row's body. This is the change that makes the tool cheap: the same

package/src/transports/config.ts

@@ -0,0 +1,110 @@
+/**
+ * WHICH TRANSPORT THIS FLEET 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.
+ *
+ * ⛔ AN UNKNOWN VALUE REFUSES AT STARTUP. It does not fall back to `tmux-push`.
+ *
+ * The reason is not tidiness. A SILENT FALLBACK AND A CORRECT DEFAULT PRODUCE
+ * IDENTICAL EVIDENCE: both give you a fleet on tmux 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.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { ROOT } from "../store.js";
+import { TMUX_PUSH, TRANSPORT_KINDS, type TransportKind } from "./types.js";
+
+/** `$AGENT_COORD_DIR/config.json`, the fleet-wide file. */
+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**.
+ *
+ * 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.
+ */
+export type ConfiguredTransport = {
+  kind: TransportKind;
+  source: "config" | "env" | "default";
+  /** Where the value came from, for an error message a human can act on. */
+  origin: string;
+};
+
+function refuse(value: string, origin: string): never {
+  throw new Error(
+    `[agent-coord-mcp] unknown transport ${JSON.stringify(value)} from ${origin}. ` +
+      `Valid: ${TRANSPORT_KINDS.join(", ")}. ` +
+      `REFUSING AT STARTUP rather than falling back to "${TMUX_PUSH}" — a silent fallback and a correct ` +
+      `default leave identical evidence, so a typo here would look exactly like a working default and the ` +
+      `transport change would appear to do nothing. Fix the value or remove it to get the default.`,
+  );
+}
+
+function asKind(value: unknown, origin: string): TransportKind {
+  if (typeof value !== "string" || value.length === 0) refuse(String(value), origin);
+  const match = TRANSPORT_KINDS.find((k) => k === value);
+  if (!match) refuse(value, origin);
+  return match;
+}
+
+let cached: ConfiguredTransport | undefined;
+
+/**
+ * Resolve the fleet's 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;
+
+  if (existsSync(TRANSPORT_CONFIG_FILE)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(TRANSPORT_CONFIG_FILE, "utf8"));
+    } catch (e) {
+      // A CONFIG FILE THAT CANNOT BE PARSED IS NOT AN ABSENT ONE. Treating it as
+      // absent would silently use the default while a file sits there stating
+      // otherwise — the same two-states-one-evidence defect as the fallback.
+      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.`,
+      );
+    }
+    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;
+  }
+
+  cached = { kind: TMUX_PUSH, source: "default", origin: `built-in default (${TMUX_PUSH})` };
+  return cached;
+}
+
+/**
+ * Drop the memo. FOR TESTS ONLY — the whole point of reading once is that
+ * production code cannot do this.
+ */
+export function resetConfiguredTransportForTests(): void {
+  cached = undefined;
+}

package/src/transports/index.ts

@@ -0,0 +1,126 @@
+/**
+ * THE REGISTRY — the one place a transport kind is turned into an implementation.
+ *
+ * `resolveTransport` is deliberately total over `TransportKind`: adding a kind to
+ * the union without registering it is a compile error here rather than a silent
+ * fall-through at a call site. Until Task 3, tmux is the only registered
+ * implementation and that is the rollback plan — the seam lands behind no config.
+ */
+import { HERDR, TMUX_PUSH, TMUX_PUSH_REMOTE, type Transport, type TransportKind } from "./types.js";
+import { TmuxTransport, type TmuxHost } from "./tmux.js";
+import { configuredTransport } from "./config.js";
+
+export * from "./types.js";
+export * from "./config.js";
+export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
+
+let host: TmuxHost | undefined;
+
+/** Wire the process-layer implementation in once, at module init. */
+export function registerTmuxHost(h: TmuxHost): void {
+  host = h;
+}
+
+export function resolveTransport(kind: TransportKind): Transport {
+  if (!host) {
+    throw new Error(
+      "transport host not registered — call registerTmuxHost() before resolveTransport(); " +
+        "this is a wiring error, not a runtime condition",
+    );
+  }
+  switch (kind) {
+    case TMUX_PUSH:
+    case TMUX_PUSH_REMOTE:
+      return new TmuxTransport(host, kind);
+    case HERDR:
+      // Task 4. Named so the union stays total and the gap is a stated absence
+      // rather than a default that silently behaves like tmux.
+      throw new Error('transport "herdr" is not implemented yet (Phase 5.4 Task 4)');
+  }
+}
+
+/* ── the ACTIVE transport, and why `running` is not read from config ────────── */
+
+/**
+ * The instance this process would actually use to deliver.
+ *
+ * Kept as an OBJECT rather than re-derived from the config value on each call,
+ * and that is the whole design. If `running` were computed by reading the config
+ * and resolving it, then `configured` and `running` would be two names for one
+ * fact and `agrees` could never be false — a check that cannot fail. The active
+ * instance is what startup actually installed, so the two can genuinely differ:
+ * a startup that refused, a process that never wired one, a test that installed
+ * another, a future path that falls back.
+ */
+let active: Transport | undefined;
+
+export function setActiveTransport(t: Transport): void {
+  active = t;
+}
+
+/** FOR TESTS ONLY — production wires the active transport once, at startup. */
+export function clearActiveTransportForTests(): void {
+  active = undefined;
+}
+
+export function activeTransport(): Transport | undefined {
+  return active;
+}
+
+/**
+ * Wire the transport this fleet is configured for. Called once at startup, and
+ * it is where an unknown config value turns into a refusal.
+ */
+export function initTransportFromConfig(): { kind: TransportKind; source: string } {
+  const conf = configuredTransport();
+  setActiveTransport(resolveTransport(conf.kind));
+  return { kind: conf.kind, source: conf.source };
+}
+
+/**
+ * WHAT THIS PROCESS IS ACTUALLY RUNNING, answered by CALLING the transport.
+ *
+ * *A config value is a label someone typed.* This asks the live object instead:
+ * it calls `available()` and puts a synthetic marker through `probe()`, and
+ * reports what came back as the evidence beside the answer. The probe is chosen
+ * to be discriminating rather than decorative — a tmux transport answers a
+ * bogus pane id with a reason that names the pane, and an implementation that
+ * does not talk to panes cannot produce that.
+ *
+ * Returns `undefined` for `kind` when nothing is wired, which is NOT the same as
+ * "tmux by default": a process with no transport delivers nothing, and reporting
+ * a default here would be the exact substitution this function exists to refuse.
+ */
+export async function runningTransport(): Promise<{
+  kind: TransportKind | undefined;
+  evidence: string;
+}> {
+  const t = active;
+  if (!t) {
+    return {
+      kind: undefined,
+      evidence: "no transport is wired in this process — nothing was called, and no default is assumed",
+    };
+  }
+  const availability = (() => {
+    try {
+      return `available()=${t.available()}`;
+    } catch (e) {
+      return `available() threw: ${(e as Error).message}`;
+    }
+  })();
+  let probeEvidence: string;
+  try {
+    const live = await t.probe({
+      agentId: "__capability_probe__",
+      transport: t.kind,
+      pid: process.pid,
+      target: "__no_such_target__",
+      since: Date.now(),
+    });
+    probeEvidence = `probe(bogus target)=${live.state}${live.state === "live" ? "" : `: ${live.reason}`}`;
+  } catch (e) {
+    probeEvidence = `probe threw: ${(e as Error).message}`;
+  }
+  return { kind: t.kind, evidence: `${availability}, ${probeEvidence}` };
+}