agent-coord-mcp 0.26.25 → 0.26.26

package/src/server.ts

@@ -845,9 +845,8 @@ async function main() {
   // branching in send_command or attach.
   try {
     const t = initTransportFromConfig();
-    if (t.source !== "default") {
-      console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
-    }
+    // ⟨q-ec020f6a⟩: no built-in default any more — every resolution has a real source, always logged.
+    console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
     // ⛔ A HERDR SEAT MUST TAIL ITS OWN INBOX, OR IT IS DEAF TO EVERY TMUX SENDER.
     // The send-time path can only see the SENDER's transport (a module-level singleton), so a
     // tmux seat's server can never type into a herdr pane. The duty belongs to the seat that
@@ -1077,6 +1076,16 @@ async function startHttp(port: number): Promise<void> {
     const tokenMap = getTokenMap();
     if (tokenMap) {
       const agent = tokenMap.get(bearer);
+      // ⛔ THE ONLY PLACE A PRE-BOUND SEAT CAN GET A TAIL. The `startTailOnBind` sites in the tool
+      // path all sit behind `bound === undefined` — the TOFU claim. Here identity arrives already
+      // decided by the bearer, that branch is unreachable, and before this line NO tail ever
+      // started under HTTP (⟨q-cdb5b007⟩: `herdrTail: []`, and send-time delivery deferring to a
+      // tail that does not exist drops the message permanently and silently).
+      //
+      // Deliberately lazy rather than a loop over the whole token map at boot: only a seat that
+      // actually connects gets a tail, so a 20-agent map does not spawn 20 timers for seats that
+      // may not exist. Idempotent — steady state is one Map lookup per request.
+      if (agent) startTailOnBind(agent);
       return agent ? { ok: true, agent } : { ok: false };
     }
     // Advisory mode: only check the shared bearer matches.

package/src/tools/herdr-tail.ts

@@ -63,8 +63,18 @@ export type TailContext = {
   hw: Map<string, number>;
   /** Last seen size per source: a source that has not grown costs one stat. */
   sizes: Map<string, number>;
+  /**
+   * ⛔ START AT EOF, NEVER AT WHATEVER THE CURSOR FILE HAPPENS TO SAY. A tail is a LIVE push
+   * mechanism, not a mail reader: nothing that predates its start belongs on the pane. Measured
+   * 2026-09-17 — a daemon restart reset every push cursor to ~0, so a tail starting from disk
+   * state would have typed a 3.4MB inbox into one seat's pane. `read_messages` still serves that
+   * history on demand; that is the verb for it.
+   */
+  seedEof: boolean;
+  /** Sources already seeded — a room discovered on a later refresh is seeded on ITS first sight, not skipped. */
+  seeded: Set<string>;
 };
-export const newContext = (): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map() });
+export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map(), seedEof, seeded: new Set() });
 
 const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
 const sizeOf = (file: string): number => {
@@ -127,6 +137,15 @@ export async function tailOnce(
     // ⭐ THE IDLE PATH: a source that has not grown since the last tick costs this one stat.
     if (ctx.sizes.get(key) === size) continue;
     ctx.sizes.set(key, size);
+    // ⛔ 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.
+    if (ctx.seedEof && !ctx.seeded.has(key)) {
+      ctx.seeded.add(key);
+      ctx.hw.set(key, size);
+      continue;
+    }
     const from = await offsetOf(agentId, src, ctx);
     if (size <= from) continue;
 
@@ -208,12 +227,12 @@ export function stopAllHerdrTails(): void {
  */
 export function ensureHerdrTail(
   agentId: string,
-  opts: { transport?: Transport; pollMs?: number; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
+  opts: { transport?: Transport; pollMs?: number; seedEof?: boolean; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
 ): { started: boolean; running: boolean; why: string } {
   const t = opts.transport ?? activeTransport();
   if (!t || t.kind !== HERDR) return { started: false, running: false, why: `transport is ${t?.kind ?? "unwired"}, not herdr — a tmux seat is woken by its pusher` };
   if (running.has(agentId)) return { started: false, running: true, why: "already tailing this agent in this process" };
-  const ctx = newContext();
+  const ctx = newContext(opts.seedEof === true);
   const run = opts.tail ?? ((id: string, c: TailContext) => tailOnce(id, { transport: t, ctx: c }));
   const rec: TailRecord = { agentId, startedAt: new Date().toISOString(), ticks: 0, delivered: 0, held: 0, lastTickAt: null, lastWhy: null, stop: () => {} };
   let inFlight = false;
@@ -237,8 +256,21 @@ export function ensureHerdrTail(
   return { started: true, running: true, why: `tailing ${agentId}'s inbox and rooms every ${opts.pollMs ?? DEFAULT_POLL_MS}ms` };
 }
 
-/** The hook the server calls at EVERY identity binding — `join`, a gated first claim, or the env var. */
+/**
+ * The hook the server calls at EVERY identity binding — `join`, a gated first claim, the env var,
+ * or (HTTP) an authenticated request from a PRE-BOUND identity.
+ *
+ * ⛔ THE BINDING TRANSITION IS NOT REACHABLE UNDER HTTP, WHICH IS WHY THIS ALSO HANGS OFF AUTH.
+ * The `bound === undefined` sites below only fire when a session CLAIMS an id. A token-authenticated
+ * daemon resolves identity per request and reports `pre-bound (N agents)`, so `bound` is never
+ * undefined and NO tail ever started — measured 2026-09-17 as `herdrTail: []` on a freshly
+ * restarted daemon whose seats had re-joined after it. With the send-time path deferring owed
+ * messages to "the recipient's own tail", a tail that never exists makes that deferral a permanent
+ * silent drop: one message behind and the seat is deaf for good (⟨q-cdb5b007⟩).
+ *
+ * Idempotent, so the per-request call costs one Map lookup once the tail is up.
+ */
 export function startTailOnBind(agentId: string, log: (line: string) => void = (l) => console.error(l)): void {
-  const r = ensureHerdrTail(agentId);
+  const r = ensureHerdrTail(agentId, { seedEof: true });
   if (r.started) log(`[agent-coord-mcp] herdr tail: ${r.why}`);
 }

package/src/tools/transport.ts

@@ -1,6 +1,5 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive, markerHoldsLiveProcess } from "./registry.js";
 import {
-  TMUX_PUSH,
   registerTmuxHost,
   activeTransport,
   HERDR,
@@ -8,7 +7,6 @@ import {
   isLocallyProbeable,
   isTmuxKind,
   paneExists,
-  probePane,
   tmuxVersion,
   targetOf,
   tmuxAvailable,
@@ -30,9 +28,9 @@ import { resolveServerIdentity } from "../server-identity.js";
 import { capabilitiesTool } from "../capabilities.js";
 import { sendMessageTool, readMessagesTool } from "./messaging.js";
 import { randomUUID } from "node:crypto";
-import { existsSync, openSync, readFileSync, watch } from "node:fs";
+import { existsSync, readFileSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { seatBuildOf, installedFrom, psReader } from "./seat-build.js";
@@ -691,158 +689,22 @@ export async function attachAgentTool(args: {
       note: "herdr socket transport: no pusher process — delivery is made in-process by this server through herdr's socket API; liveness is herdr's own pane status",
     };
   }
-  const target = args.tmuxTarget ?? process.env.TMUX_PANE;
-  if (!target) {
-    return {
-      ok: false,
-      error:
-        "tmuxTarget not provided and the MCP server is not running inside tmux (no $TMUX_PANE). Pass tmuxTarget explicitly (e.g. '%42' or 'session:window.pane').",
-    };
-  }
-
-  // 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: ${targetProbe.stderr}`,
-    };
-  }
-
-  // If something's already attached, refuse rather than spawn a second pusher.
-  const existing = await readJson<TransportMarker | null>(transportFile(args.agentId), null);
-  if (markerHoldsLiveProcess(existing)) {
-    return {
-      ok: false,
-      error: `agent '${args.agentId}' already has a live ${existing!.transport} attached (pid ${existing!.pid}). Call detach_agent first.`,
-      existing,
-    };
-  }
-  // Clean up dead marker, if any.
-  if (existing) await deleteFile(transportFile(args.agentId));
-
-  const pusher = resolvePusherPath();
-  if (!existsSync(pusher)) {
-    return { ok: false, error: `tmux-pusher not found at ${pusher}` };
-  }
-
-  // Detached spawn so the pusher outlives this MCP request/process.
-  const log = logFile(args.agentId, "pusher");
-  await fsp.mkdir(path.dirname(log), { recursive: true });
-  await fsp.mkdir(path.dirname(pidFile(args.agentId, "pusher")), { recursive: true });
-  await fsp.mkdir(path.dirname(transportFile(args.agentId)), { recursive: true });
-  const logFd = openSync(log, "a");
-  // Default: deliver room broadcasts too. The bus is chat-first — silence on
-  // a room post is a worse failure mode than a slightly noisier pane. Callers
-  // who want DM-only can pass includeRoom:false explicitly.
-  const includeRoom = args.includeRoom !== false;
-  // Use the exact node binary running this server, not bare "node" — the MCP
-  // server is often launched via an absolute path (nvm/Homebrew/bundled
-  // runtime) that isn't on the spawned child's PATH, which would silently fail
-  // the pusher launch ("attached but nothing arrives").
-  // `--agent <id>` is inert to the pusher (env stays authoritative) but puts
-  // the agentId in argv, so a pattern kill can be scoped to ONE pusher
-  // (`pkill -f "tmux-pusher.mjs --agent <id>"`). Without it the only matchable
-  // pattern was the script path, and a `pkill -f tmux-pusher.mjs` during one
-  // agent's cleanup silently detached every live agent on the bus (2026-07-28).
-  const child = spawn(process.execPath, [pusher, "--agent", args.agentId], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: {
-      ...process.env,
-      AGENT_COORD_ID: args.agentId,
-      AGENT_COORD_TMUX_TARGET: target,
-      ...(includeRoom ? { AGENT_COORD_INCLUDE_ROOM: "1" } : {}),
-      ...(args.allowlist && args.allowlist.length > 0
-        ? { AGENT_COORD_ALLOWLIST: args.allowlist.join(",") }
-        : {}),
-      ...(args.debounceMs ? { AGENT_COORD_DEBOUNCE_MS: String(args.debounceMs) } : {}),
-    },
-  });
-  child.unref();
-  const pid = child.pid;
-  if (!pid) return { ok: false, error: "spawn returned no pid" };
-
-  // Write pid file (for scripts) and transport marker (for list_agents).
-  await fsp.writeFile(pidFile(args.agentId, "pusher"), String(pid), "utf8");
-  // Stamp the pusher source's freshness so doctor() can flag a stale daemon if
-  // it outlives a later upgrade of the on-disk code (see v0.8.1 → v0.8.2 bug
-  // report: control commands silently dropped by pre-v0.8 in-memory code).
-  const scriptMtime = newestPusherSourceMtime();
-  const marker: TransportMarker = {
-    agentId: args.agentId,
-    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,
-    // Provenance: the build identity THIS server loaded at startup — not a
-    // fresh stat of dist/, because the code doing the stamping is the loaded
-    // code, and after an in-place rebuild the two differ (that difference is
-    // exactly what doctor's provenance check exists to surface).
-    serverBuildMtime: SERVER_BUILD_MTIME,
-    // WHAT this transport carries, recorded by the code that decides it.
-    // `includeRoom` is what the pusher is actually spawned with a few lines
-    // above, so the marker cannot claim a capability the process was not
-    // given — the marker and the spawn come from one value, not two.
-    rooms: includeRoom,
-  };
-  // Use updateJson so it lockfile-protects and creates the file atomically.
-  await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
-
-  // Best-effort scan for a peek-coord.mjs hook wired to the same agentId —
-  // both consumers share the cursor file and would race / double-deliver.
-  const conflictingHook = await detectPeekCoordHook(args.agentId);
-
+  // ⟨q-ec020f6a⟩ slice C — local tmux-push DELETED outright: 0 of 13 live seats used it,
+  // and keeping it meant a second delivery mechanism (hooks/tmux-pusher.mjs, now removed)
+  // plus a role-card precondition that halted every live herdr seat on a false requirement.
+  // attach_agent handles exactly one kind now. A remote seat never came through here in
+  // the first place — it registers via report_transport (scripts/coord-pusher.mjs) — so
+  // this refuses rather than silently trying (and failing) to spawn a script that no
+  // longer exists.
   return {
-    ok: true,
-    agentId: args.agentId,
-    transport: TMUX_PUSH,
-    tmuxTarget: target,
-    pid,
-    log,
-    ...(conflictingHook
-      ? {
-          warnings: [
-            `peek-coord.mjs hook for agentId='${args.agentId}' detected in ${conflictingHook}. ` +
-              `Running both transports causes double-delivery — disable one. ` +
-              `Recommend removing the peek-coord hook entry since tmux-push supersedes it.`,
-          ],
-        }
-      : {}),
+    ok: false,
+    error:
+      `attach_agent only attaches the herdr transport now (this fleet's active transport is ` +
+      `${activeT ? `'${activeT.kind}'` : "unconfigured"}) — local tmux-push was removed (⟨q-ec020f6a⟩). ` +
+      `A remote seat registers via report_transport, not attach_agent.`,
   };
 }
 
-async function detectPeekCoordHook(agentId: string): Promise<string | undefined> {
-  const home = process.env.HOME ?? "";
-  const cwd = process.cwd();
-  const candidates = [
-    path.join(home, ".claude", "settings.json"),
-    path.join(home, ".claude", "settings.local.json"),
-    path.join(cwd, ".claude", "settings.json"),
-    path.join(cwd, ".claude", "settings.local.json"),
-  ];
-  for (const file of candidates) {
-    if (!existsSync(file)) continue;
-    try {
-      const raw = await fsp.readFile(file, "utf8");
-      if (raw.includes("peek-coord.mjs") && raw.includes(`AGENT_COORD_ID=${agentId}`)) {
-        return file;
-      }
-    } catch {
-      // unreadable, skip
-    }
-  }
-  return undefined;
-}
-
 export const detachAgentSchema = {
   agentId: z.string().min(1),
 };

package/src/transports/config.ts

@@ -7,18 +7,27 @@
  * 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`.
+ * ⛔ 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 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.
+ * IDENTICAL EVIDENCE: both give you a fleet 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.
+ *
+ * ⟨q-ec020f6a⟩ THERE IS NO BUILT-IN DEFAULT ANY MORE, for the identical reason.
+ * `tmux-push` (0 of 13 live seats) used to be it; deleting that kind without
+ * 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 —
+ * the exact silent-guess failure ⟨q-e439e4ad⟩ spent a day fixing, moved one
+ * layer up. So: zero configuration REFUSES, naming the kinds that exist.
  */
 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";
+import { 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");
@@ -39,7 +48,7 @@ export const TRANSPORT_ENV_VAR = "AGENT_COORD_TRANSPORT";
  */
 export type ConfiguredTransport = {
   kind: TransportKind;
-  source: "config" | "env" | "default";
+  source: "config" | "env";
   /** Where the value came from, for an error message a human can act on. */
   origin: string;
 };
@@ -48,9 +57,9 @@ 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.`,
+      `REFUSING AT STARTUP rather than falling back to anything — a silent fallback and a correct ` +
+      `default leave identical evidence, so a typo here would look exactly like a working value and the ` +
+      `transport change would appear to do nothing. Fix the value or remove it (⟨q-ec020f6a⟩: there is no default to fall back to).`,
   );
 }
 
@@ -97,8 +106,12 @@ export function configuredTransport(): ConfiguredTransport {
     return cached;
   }
 
-  cached = { kind: TMUX_PUSH, source: "default", origin: `built-in default (${TMUX_PUSH})` };
-  return cached;
+  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.`,
+  );
 }
 
 /**

package/src/transports/herdr.ts

@@ -257,6 +257,24 @@ export class HerdrTransport implements Transport {
     if (!avail.available) throw new Error(`herdr transport cannot attach '${args.agentId}': ${avail.reason}`);
     let target = args.target ?? this.#env.HERDR_PANE_ID;
     if (!target) {
+      // ⟨q-e439e4ad⟩ `herdr pane current` asks HERDR FOR WHATEVER PANE IS CURRENTLY
+      // FOCUSED ON THIS HOST — under stdio that is correct, because the server process
+      // itself lives inside the caller's own pane (the same relationship $TMUX_PANE has
+      // to a tmux server). AGENT_COORD_HTTP_PORT set means this process is instead the
+      // shared bus DAEMON: one long-lived process with no pane of its own, answering
+      // every seat on the host. "Current" there names whichever terminal a human last
+      // focused — measured attaching two different seats onto ANOTHER FLEET's panes,
+      // both calls returning `ok`. Same rule as transports/config.ts's unknown-transport
+      // refusal: a silent fallback and a correct default produce identical evidence, so
+      // this refuses instead of guessing.
+      if (this.#env.AGENT_COORD_HTTP_PORT) {
+        throw new Error(
+          `herdr target not provided for '${args.agentId}': this server is the shared HTTP daemon ` +
+            `(AGENT_COORD_HTTP_PORT set) and has no pane of its own, so \`herdr pane current\` would name ` +
+            `whichever pane last had focus on this host, not '${args.agentId}''s. Pass target explicitly ` +
+            `(e.g. 'w2:p1').`,
+        );
+      }
       const cur = this.#run(["pane", "current"]);
       target = paneOf(cur)?.pane_id;
     }

package/src/transports/index.ts

@@ -6,7 +6,7 @@
  * 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, TRANSPORT_KINDS, type Transport, type TransportKind } from "./types.js";
+import { HERDR, TMUX_PUSH_REMOTE, TRANSPORT_KINDS, type Transport, type TransportKind } from "./types.js";
 import { TmuxTransport, type TmuxHost } from "./tmux.js";
 import { HerdrTransport } from "./herdr.js";
 import { configuredTransport } from "./config.js";
@@ -31,7 +31,8 @@ export function resolveTransport(kind: TransportKind): Transport {
     );
   }
   switch (kind) {
-    case TMUX_PUSH:
+    // ⟨q-ec020f6a⟩ local tmux-push deleted outright — TmuxTransport now only ever
+    // backs the remote kind. Kept fully intact: only this construction site changed.
     case TMUX_PUSH_REMOTE:
       return new TmuxTransport(host, kind);
     case HERDR:

package/src/transports/tmux.ts

@@ -14,7 +14,7 @@
  */
 import { spawnSync } from "node:child_process";
 import type { ControlCommand, Liveness, Transport, TransportMarker, TransportKind } from "./types.js";
-import { TMUX_PUSH, isLocallyProbeable, isTmuxKind, targetOf } from "./types.js";
+import { TMUX_PUSH_REMOTE, isLocallyProbeable, isTmuxKind, targetOf } from "./types.js";
 
 /**
  * The parts of delivery that belong to the PROCESS layer, not to tmux.
@@ -87,7 +87,10 @@ export class TmuxTransport implements Transport {
   readonly kind: TransportKind;
   #host: TmuxHost;
 
-  constructor(host: TmuxHost, kind: TransportKind = TMUX_PUSH) {
+  // ⟨q-ec020f6a⟩ local tmux-push deleted: this class now only ever backs the remote kind,
+  // so the default (used only by tests that omit `kind`) follows that — everything else
+  // in this file is unchanged, per the slice's "keep TmuxTransport fully intact" scope.
+  constructor(host: TmuxHost, kind: TransportKind = TMUX_PUSH_REMOTE) {
     this.#host = host;
     this.kind = kind;
   }

package/src/transports/types.ts

@@ -27,17 +27,32 @@
  * instead of reading the field, and a `string` discriminant cannot tell the
  * compiler that a branch was missed. Not a two-member union either — see (1).
  */
+/**
+ * ⟨q-ec020f6a⟩ LOCAL tmux-push was DELETED outright (0 of 13 live seats used it; keeping
+ * it meant a second delivery mechanism — hooks/tmux-pusher.mjs, now removed — plus a
+ * role-card precondition that halted every live herdr seat on a false requirement).
+ *
+ * `TMUX_PUSH` stays DEFINED AND EXPORTED, but OUT of `TransportKind`/`TRANSPORT_KINDS`, for
+ * exactly one reason: a marker written to disk before this change can still literally read
+ * `"tmux-push"`, and `isLocallyProbeable`/`isTmuxKind` below must keep classifying that
+ * HISTORICAL value correctly (never `"dead"` where it used to read `"unknown"`) even
+ * though nothing can construct a NEW one — `resolveTransport` has no case for it and
+ * `config.ts` refuses it. Classifying old data and constructing new data are different
+ * questions; removing it from the union answers only the second.
+ */
 export const TMUX_PUSH = "tmux-push" as const;
 export const TMUX_PUSH_REMOTE = "tmux-push-remote" as const;
 export const HERDR = "herdr" as const;
 
-export type TransportKind = typeof TMUX_PUSH | typeof TMUX_PUSH_REMOTE | typeof HERDR;
+export type TransportKind = typeof TMUX_PUSH_REMOTE | typeof HERDR;
 
-export const TRANSPORT_KINDS: readonly TransportKind[] = [TMUX_PUSH, TMUX_PUSH_REMOTE, HERDR] as const;
+export const TRANSPORT_KINDS: readonly TransportKind[] = [TMUX_PUSH_REMOTE, HERDR] as const;
 
 /**
- * The tmux family. Both members are delivered by a pusher process typing into a
- * pane; they differ in WHERE that pane is, which is why liveness splits below.
+ * The tmux family, for LIVENESS CLASSIFICATION of whatever a marker on disk says —
+ * including the historical, no-longer-constructible local kind (`TMUX_PUSH`, above).
+ * Both members are delivered by a pusher process typing into a pane; they differed in
+ * WHERE that pane was, which is why liveness splits below.
  *
  * THIS IS THE ONE PLACE THE TMUX LITERALS LIVE. Twelve call sites used to spell
  * them; they now ask.