agent-coord-mcp 0.26.25 → 0.26.27

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

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.