agent-coord-mcp 0.26.22 → 0.26.24

package/src/transports/herdr.ts

@@ -0,0 +1,385 @@
+/**
+ * THE HERDR TRANSPORT — the second implementation of the seam (Phase 5.4 Task 4).
+ *
+ * herdr is a RUST BINARY (brew / herdr.dev / GitHub releases), NOT an npm package:
+ * `npm view herdr` answers 0.0.0 "Reserved package name" (spike 1.1). Nothing here is
+ * imported; every call is `herdr <subcommand>` over the socket API on this host, through
+ * one injectable runner so the transport can be exercised without a herdr server and
+ * measured against one when it is there.
+ *
+ * WHAT IS DIFFERENT FROM TMUX, and why each difference is a stated behaviour rather
+ * than a quiet default:
+ *   · NO PUSHER PROCESS. Delivery is a socket call made by the server itself; a marker
+ *     carries pid 0. Liveness is therefore never a pid heuristic — `probe` asks herdr
+ *     for the pane and its OWN `agent_status` (spike 1.4: live / wedged / killed are
+ *     three distinguishable answers there, which they are not on tmux).
+ *   · ERRORS ARE JSON, ON EITHER STREAM. `herdr pane get w999:p1` prints
+ *     {"error":{"code":"pane_not_found",…}} — measured on stdout with exit 0 in one call
+ *     and on stderr in another (a pane closed moments before read as "could not describe"
+ *     until the runner parsed stderr too). The runner parses whichever stream carries a
+ *     JSON body; the exit code alone would call failures successes.
+ *   · KEY NAMES ARE NOT PORTABLE. `ctrl+u` is accepted, `C-u` / `ctrl-u` are rejected
+ *     with {"error":{"code":"invalid_key"}} (spike, and measured again here). The seam
+ *     takes INTENTS; the one place a key name is spelled is `herdrKeyName`, which
+ *     REFUSES a tmux-vocabulary name rather than translating it by guess.
+ *   · THE ENTER RACE IS REAL. `send-text` then `send-keys enter` did not submit once in
+ *     the spike; the line sat in Claude's input box until a second enter. `push` and
+ *     `sendControl` VERIFY by reading the pane back and retry the enter once, and report
+ *     how many enters it took — measured per delivery, never assumed away.
+ *   · THE SLASH IS EATEN DOWNSTREAM OF ANY TRANSPORT (spike 1.3, ⟨q-f14692ca⟩ struck):
+ *     Claude Code interprets a leading `/` however the characters arrive. This transport
+ *     delivers bytes verbatim and makes no claim about what the reader does with them.
+ *   · ABSENT BINARY / STOPPED SERVER → an explicit refusal that NAMES herdr. Never a
+ *     silent fall-through to tmux: the config layer already refuses unknown kinds for the
+ *     same reason (identical evidence for a typo and a default).
+ */
+import { spawnSync } from "node:child_process";
+import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
+import { HERDR, TICK_READS_AS, TICK_STORED_AS, targetOf } from "./types.js";
+
+export type HerdrError = { code: string; message: string };
+export type HerdrResult = {
+  ok: boolean;
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  /** Parsed JSON body when herdr printed one. */
+  json?: unknown;
+  /** herdr's own error object, or a synthetic one for a missing binary. */
+  error?: HerdrError;
+  /** The binary itself is not on PATH. */
+  absent?: boolean;
+};
+export type HerdrRunner = (args: string[]) => HerdrResult;
+
+export const HERDR_BINARY = "herdr";
+export const HERDR_ABSENT_MESSAGE =
+  `herdr binary not found on PATH — herdr is a Rust binary (brew install herdr, or https://herdr.dev), ` +
+  `NOT an npm package (npm's "herdr" is a reserved 0.0.0 name). Install it, or use the tmux-push transport.`;
+
+/**
+ * Interpret a herdr reply — PURE, so the one rule it holds (a JSON error body on either
+ * stream is a refusal, whatever the exit code) is testable without a herdr on the host.
+ */
+export function interpretHerdrReply(r: { status: number | null; stdout?: string | null; stderr?: string | null }): HerdrResult {
+  const stdout = r.stdout ?? "";
+  const stderr = r.stderr ?? "";
+  let json: unknown;
+  for (const stream of [stdout, stderr]) {
+    const trimmed = stream.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try { json = JSON.parse(trimmed); break; } catch { /* not a JSON body */ }
+  }
+  const err = (json as { error?: HerdrError } | undefined)?.error;
+  if (err && typeof err.code === "string") return { ok: false, status: r.status, stdout, stderr, json, error: err };
+  if (r.status !== 0) return { ok: false, status: r.status, stdout, stderr, json, error: { code: "exit", message: (stderr || stdout).trim() || `herdr exited ${r.status}` } };
+  return { ok: true, status: r.status, stdout, stderr, json };
+}
+
+/** Run `herdr <args>` and interpret the reply. */
+export function defaultHerdrRunner(args: string[]): HerdrResult {
+  const r = spawnSync(HERDR_BINARY, args, { encoding: "utf8" });
+  if (r.error && (r.error as NodeJS.ErrnoException).code === "ENOENT") {
+    return { ok: false, status: null, stdout: "", stderr: "", absent: true, error: { code: "binary_absent", message: HERDR_ABSENT_MESSAGE } };
+  }
+  return interpretHerdrReply({ status: r.status, stdout: r.stdout, stderr: r.stderr });
+}
+
+/**
+ * THE KEY VOCABULARY, in one place. Intents on the left, herdr's names on the right.
+ * A tmux-vocabulary name (`C-u`, `ctrl-u`, `M-x`) is REFUSED, never translated by guess:
+ * herdr would reject it as invalid_key, and a transport that "helpfully" rewrote it could
+ * just as easily rewrite it wrong and type garbage into a pane.
+ */
+export const HERDR_KEYS: Readonly<Record<string, string>> = Object.freeze({
+  enter: "enter",
+  escape: "esc",
+  "clear-line": "ctrl+u",
+});
+export function herdrKeyName(intentOrName: string): { ok: true; key: string } | { ok: false; error: string } {
+  const s = String(intentOrName ?? "").trim();
+  if (/^(?:C|M|S)-/i.test(s) || /^(?:ctrl|alt|meta|shift)-/i.test(s)) {
+    return { ok: false, error: `key '${s}' is tmux vocabulary and herdr rejects it as invalid_key — the herdr form is '${s.replace(/^(?:C|ctrl)-/i, "ctrl+").replace(/^(?:M|alt|meta)-/i, "alt+")}'; refused rather than guessed` };
+  }
+  if (HERDR_KEYS[s]) return { ok: true, key: HERDR_KEYS[s] };
+  if (/^[a-z0-9]+(?:\+[a-z0-9]+)*$/.test(s)) return { ok: true, key: s };
+  return { ok: false, error: `key '${s}' is not a herdr key name (letters, digits and '+', e.g. ctrl+u) and not a known intent (${Object.keys(HERDR_KEYS).join(", ")})` };
+}
+
+type PaneInfo = { pane_id?: string; agent_status?: string; agent?: string; workspace_id?: string };
+type ProcessInfo = { foreground_processes?: { argv?: string[]; pid?: number; name?: string }[]; shell_pid?: number };
+
+function paneOf(r: HerdrResult): PaneInfo | undefined {
+  const j = r.json as { result?: { pane?: PaneInfo; root_pane?: PaneInfo } } | undefined;
+  return j?.result?.pane ?? j?.result?.root_pane;
+}
+function processInfoOf(r: HerdrResult): ProcessInfo | undefined {
+  return (r.json as { result?: { process_info?: ProcessInfo } } | undefined)?.result?.process_info;
+}
+const LIVE_STATUSES = new Set(["idle", "working", "blocked", "done"]);
+
+export type HerdrTransportOptions = {
+  run?: HerdrRunner;
+  /** Milliseconds to wait before reading a pane back after typing. */
+  settleMs?: number;
+  /** Sleep, injectable so tests do not wait. */
+  sleep?: (ms: number) => void;
+  /** Lines of pane to read back when verifying a delivery. */
+  readLines?: number;
+};
+
+export class HerdrTransport implements Transport {
+  readonly kind: TransportKind = HERDR;
+  #run: HerdrRunner;
+  #settleMs: number;
+  #sleep: (ms: number) => void;
+  #readLines: number;
+
+  constructor(opts: HerdrTransportOptions = {}) {
+    this.#run = opts.run ?? defaultHerdrRunner;
+    // MEASURED on a shell pane in a task-owned workspace: after a single enter the output had
+    // rendered by 400 ms and not by 150 ms — below that, render lag reads as an unsubmitted
+    // line and the retry fires an empty enter (harmless, but counted). The genuine lost enter
+    // the spike measured is Claude's input box; the retry exists for that, bounded to one.
+    this.#settleMs = opts.settleMs ?? 400;
+    this.#sleep = opts.sleep ?? ((ms) => { const end = Date.now() + ms; while (Date.now() < end) { /* spin: tiny and rare */ } });
+    this.#readLines = opts.readLines ?? 12;
+  }
+
+  /** Is herdr on this host AND is its server running? Both, or the reason. */
+  availability(): { available: boolean; reason: string } {
+    const r = this.#run(["status"]);
+    if (r.absent) return { available: false, reason: HERDR_ABSENT_MESSAGE };
+    if (!r.ok) return { available: false, reason: `herdr status failed: ${r.error?.message ?? r.stderr}` };
+    const running = /server:[\s\S]*status:\s*running/.test(r.stdout);
+    return running
+      ? { available: true, reason: `herdr server running (${(r.stdout.match(/version:\s*(\S+)/) ?? [])[1] ?? "version unread"})` }
+      : { available: false, reason: `herdr binary present but its server is not running (herdr status: ${r.stdout.trim().split("\n").slice(-2).join(" ")}) — start herdr, or use the tmux-push transport` };
+  }
+  available(): boolean {
+    return this.availability().available;
+  }
+
+  /**
+   * Attach = verify the pane and return a marker. No process is spawned: the marker's pid
+   * is 0 and its `target` is the herdr pane id. Persisting the marker is the tool's job,
+   * exactly as for tmux.
+   */
+  async attach(args: { agentId: string; target?: string; includeRoom?: boolean; allowlist?: string[]; debounceMs?: number }): Promise<TransportMarker> {
+    const avail = this.availability();
+    if (!avail.available) throw new Error(`herdr transport cannot attach '${args.agentId}': ${avail.reason}`);
+    let target = args.target ?? process.env.HERDR_PANE_ID;
+    if (!target) {
+      const cur = this.#run(["pane", "current"]);
+      target = paneOf(cur)?.pane_id;
+    }
+    if (!target) {
+      throw new Error("herdr target not provided and this process is not inside a herdr pane (no HERDR_PANE_ID, `herdr pane current` answered nothing). Pass target explicitly (e.g. 'w2:p1').");
+    }
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) throw new Error(`herdr pane '${target}' not found: ${got.error?.message ?? got.stderr}`);
+    return {
+      agentId: args.agentId,
+      transport: HERDR,
+      pid: 0,
+      target,
+      tmuxTarget: target,
+      since: Date.now(),
+      rooms: args.includeRoom !== false,
+    };
+  }
+
+  /** Does the pane exist, per herdr, through THIS transport's runner? null = could not ask. */
+  paneExists(target: string): boolean | null {
+    return herdrPaneExists(target, this.#run);
+  }
+
+  /** Nothing to kill: there is no pusher. The tool deletes the marker. */
+  async detach(_agentId: string): Promise<void> {
+    return;
+  }
+
+  /**
+   * Type `text` into the pane and press enter; VERIFY by reading the pane back, and if
+   * the line is still sitting unsubmitted (the spike's race), press enter once more.
+   * Reports the enters it took so the race is measured on every delivery.
+   */
+  async push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string; enters?: number; verified?: boolean }> {
+    const avail = this.availability();
+    if (!avail.available) return { delivered: false, error: avail.reason };
+    const target = targetOf(marker);
+    if (!target) return { delivered: false, error: "no target recorded on the marker" };
+    const typed = this.#run(["pane", "send-text", target, text]);
+    if (!typed.ok) return { delivered: false, error: `send-text to ${target} refused: ${typed.error?.message ?? typed.stderr}` };
+    const enterKey = herdrKeyName("enter");
+    if (!enterKey.ok) return { delivered: false, error: enterKey.error };
+    let enters = 0;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const pressed = this.#run(["pane", "send-keys", target, enterKey.key]);
+      if (!pressed.ok) return { delivered: false, error: `send-keys enter to ${target} refused: ${pressed.error?.message ?? pressed.stderr}`, enters };
+      enters++;
+      this.#sleep(this.#settleMs);
+      const pending = this.#stillPending(target, text);
+      if (pending === false) return { delivered: true, enters, verified: true };
+      if (pending === null) return { delivered: true, enters, verified: false };
+    }
+    return { delivered: false, enters, verified: true, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+  }
+
+  /**
+   * Read the pane back: is the typed text still the LAST non-empty line (unsubmitted)?
+   * true = pending · false = submitted · null = could not read (unverified, not failed).
+   */
+  #stillPending(target: string, text: string): boolean | null {
+    const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(this.#readLines), "--format", "text"]);
+    if (!read.ok) return null;
+    const lines = read.stdout.split("\n").map((l) => l.replace(/\s+$/, "")).filter((l) => l.trim().length > 0);
+    const last = lines.at(-1) ?? "";
+    const firstLine = text.split("\n")[0];
+    return last.endsWith(firstLine) && !/^[⏺✔✖]/.test(last);
+  }
+
+  /**
+   * THREE ANSWERS FROM HERDR'S OWN STATUS, never a pid heuristic:
+   *   · not a herdr marker / no target / herdr unavailable → unknown, naming which
+   *   · pane_not_found                                     → dead
+   *   · agent_status idle | working | blocked | done       → live (blocked IS live: it waits on a person)
+   *   · agent_status unknown, a foreground process present → unknown, naming the process (the wedged shape)
+   *   · agent_status unknown, nothing in the foreground    → unknown (a shell pane nobody is in)
+   */
+  async probe(marker: TransportMarker): Promise<Liveness> {
+    if (marker.transport !== HERDR) return { state: "unknown", reason: `transport "${marker.transport}" is not herdr` };
+    const target = targetOf(marker);
+    if (!target) return { state: "unknown", reason: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { state: "unknown", reason: avail.reason };
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) {
+      if (got.error?.code === "pane_not_found") return { state: "dead", reason: `herdr reports pane ${target} not found (${got.error.message})` };
+      return { state: "unknown", reason: `herdr could not describe pane ${target}: ${got.error?.message ?? got.stderr}` };
+    }
+    const status = String(paneOf(got)?.agent_status ?? "unknown");
+    if (LIVE_STATUSES.has(status)) return { state: "live" };
+    const proc = this.#run(["pane", "process-info", "--pane", target]);
+    const fg = processInfoOf(proc)?.foreground_processes ?? [];
+    if (fg.length) {
+      const p = fg[0];
+      return { state: "unknown", reason: `herdr reports agent_status "${status}" for pane ${target}; foreground process ${JSON.stringify(p.argv ?? [p.name])} (pid ${p.pid}) — present but not a recognised agent` };
+    }
+    return { state: "unknown", reason: `herdr reports agent_status "${status}" for pane ${target} and no foreground process` };
+  }
+
+  /**
+   * A control command is typed as `/<cmd>` and verified to have LEFT the input, with the
+   * same enter-race handling as push. All three commands ride the path the spike measured
+   * for /clear; compact and reload-skills are the same delivery path (spike: inferred,
+   * not measured) and are said so in the result.
+   */
+  async sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string; enters?: number; note?: string }> {
+    const r = await this.push(marker, `/${cmd}`);
+    if (!r.delivered) return { ok: false, error: r.error ?? "control not delivered", enters: r.enters };
+    return {
+      ok: true,
+      enters: r.enters,
+      note: cmd === "clear" ? "measured end to end in the spike" : `same delivery path as /clear; ${cmd} itself was inferred, not measured, by the spike`,
+    };
+  }
+
+  /**
+   * ⟨q-1c95f7d4⟩ 5.1 — THE EXTERNAL TICK, CONSUMED. herdr's own `agent_status` for the
+   * pane, which is the signal this fleet has never had: our liveness is pid-existence and
+   * our activity is VCS commits, so a THINKING lane and a WEDGED lane are identical to us.
+   *
+   * ⛔ `unknown` AND `done` ARE NOT SEAT STATES AND MUST NOT READ AS CALM. `unknown` is
+   * herdr saying it has no agent there (the shape a plain shell pane returns, measured);
+   * `done` is a finished session, not a moving seat. Both come back UNREADABLE, so the
+   * caller counts them as unmeasured rather than crediting coverage — the exact inversion
+   * (blind read as quiet) that `stall_check` shipped and this task exists to end.
+   */
+  async readTick(marker: TransportMarker): Promise<TickReading> {
+    if (marker.transport !== HERDR) return { readable: false, why: `transport "${marker.transport}" has no external tick — only a herdr marker does` };
+    const target = targetOf(marker);
+    if (!target) return { readable: false, why: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { readable: false, why: avail.reason };
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) {
+      if (got.error?.code === "pane_not_found") return { readable: false, why: `herdr reports pane ${target} not found — a gone pane has no tick (and probe calls it dead)` };
+      return { readable: false, why: `herdr could not describe pane ${target}: ${got.error?.message ?? got.stderr}` };
+    }
+    const status = String(paneOf(got)?.agent_status ?? "unknown");
+    const state = TICK_READS_AS[status];
+    if (state) return { readable: true, state, source: `herdr pane ${target}` };
+    return { readable: false, why: `herdr reports agent_status "${status}" for pane ${target} — no agent state is published there, which is a MISSING signal, not a calm seat` };
+  }
+
+  /**
+   * ⟨q-1c95f7d4⟩ Task 1's open question — PUBLISH, and it needs a receipt it does not get.
+   *
+   * MEASURED 2026-09-15 in a workspace of my own: `herdr pane report-agent <pane> --source
+   * coord-mcp --agent <label> --state blocked` prints NOTHING and exits 0, and the pane
+   * then reads `"agent":"<label>","agent_status":"blocked"` where a second earlier it read
+   * `unknown` with no agent field. ⛔ A WRITE WITH NO OUTPUT IS A WRITE WITH NO RECEIPT:
+   * exit 0 here says the CLI parsed the arguments, not that the pane carries the state, and
+   * a second `report-agent` overwrites the first with the same silence. So this method does
+   * not trust the exit code — it READS THE PANE BACK and reports `ok` only when the pane
+   * carries both the agent label we published and the state we published. An unverifiable
+   * write is returned as an error naming what the pane actually says.
+   *
+   * ⚠ WHAT A WRONG PUBLISH COSTS, stated because the write is silent and destructive:
+   * herdr keeps ONE agent state per pane, so publishing to a pane this bus does not own
+   * overwrites whatever that pane's real agent last reported, with no history and no
+   * notification to the owner — a fleet watching herdr would then read our fiction as the
+   * seat's own signal. Hence the marker gate above (`transport !== HERDR` refuses): we
+   * publish only to panes recorded as herdr seats of this bus, never to a pane id passed in
+   * from anywhere else.
+   */
+  async publishTick(marker: TransportMarker, state: TickState, opts: { message?: string; source?: string } = {}): Promise<{ ok: boolean; error?: string; verified?: boolean }> {
+    if (marker.transport !== HERDR) return { ok: false, error: `refusing to publish state for a "${marker.transport}" seat — herdr keeps one agent state per pane and a publish to a pane this bus does not own would silently overwrite its owner's signal` };
+    const target = targetOf(marker);
+    if (!target) return { ok: false, error: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { ok: false, error: avail.reason };
+    const source = opts.source ?? "coord-mcp";
+    const args = ["pane", "report-agent", target, "--source", source, "--agent", marker.agentId, "--state", state];
+    if (opts.message) args.push("--message", opts.message);
+    const wrote = this.#run(args);
+    if (!wrote.ok) return { ok: false, error: `herdr refused the report: ${wrote.error?.message ?? wrote.stderr}` };
+    // THE RECEIPT IS THE READ-BACK, never the exit code.
+    const back = this.#run(["pane", "get", target]);
+    if (!back.ok) return { ok: false, verified: false, error: `published, but the pane could not be read back to verify it: ${back.error?.message ?? back.stderr}` };
+    const pane = paneOf(back);
+    const gotAgent = String(pane?.agent ?? "");
+    const gotState = String(pane?.agent_status ?? "");
+    // VERIFIED AGAINST WHAT herdr STORES, not against what we sent: a published `idle`
+    // comes back as `done` (TICK_STORED_AS, measured). Comparing to the sent word would
+    // call every idle publish a failure; comparing to the stored word is the receipt.
+    const expected = TICK_STORED_AS[state];
+    if (gotAgent === marker.agentId && gotState === expected) return { ok: true, verified: true };
+    return { ok: false, verified: false, error: `published --agent ${marker.agentId} --state ${state} (herdr stores that as "${expected}"), but pane ${target} reads agent "${gotAgent || "(none)"}" state "${gotState || "(none)"}" — the write did not land as published` };
+  }
+
+  /**
+   * No pusher to kill. A herdr marker whose pane is gone is reaped (the caller deletes
+   * the marker); an unknown answer is unprobeable; a live pane is left alone.
+   */
+  async reapWedged(markers: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }> {
+    const reaped: string[] = [];
+    const unprobeable: string[] = [];
+    for (const marker of markers) {
+      const live = await this.probe(marker);
+      if (live.state === "dead") reaped.push(marker.agentId);
+      else if (live.state === "unknown") unprobeable.push(marker.agentId);
+    }
+    return { reaped, unprobeable };
+  }
+}
+
+/** Synchronous pane-existence read for the registry's liveness path (no pid to check). */
+export function herdrPaneExists(target: string, run: HerdrRunner = defaultHerdrRunner): boolean | null {
+  const r = run(["pane", "get", target]);
+  if (r.absent) return null;
+  if (r.ok) return true;
+  if (r.error?.code === "pane_not_found") return false;
+  return null;
+}

package/src/transports/index.ts

@@ -6,13 +6,15 @@
  * 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 { HERDR, TMUX_PUSH, 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";
 
 export * from "./types.js";
 export * from "./config.js";
 export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
+export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult } from "./herdr.js";
 
 let host: TmuxHost | undefined;
 
@@ -33,9 +35,13 @@ export function resolveTransport(kind: TransportKind): Transport {
     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)');
+      // Task 4: the socket transport. No host object — there is no pusher process to
+      // inject; every call is `herdr <subcommand>` through the transport's own runner.
+      return new HerdrTransport();
+    default:
+      // Unreachable for a TransportKind; reachable from JS with a string. A designed
+      // refusal, never a default that behaves like tmux.
+      throw new Error(`unknown transport kind ${JSON.stringify(kind)} — valid: ${TRANSPORT_KINDS.join(", ")}`);
   }
 }
 

package/src/transports/types.ts

@@ -154,6 +154,53 @@ export type Liveness =
   | { state: "dead"; reason: string }
   | { state: "unknown"; reason: string };
 
+/**
+ * ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — THE EXTERNAL TICK'S VOCABULARY, TAKEN FROM THE TOOL THAT
+ * OWNS IT. Measured 2026-09-15 in a workspace of my own: `herdr pane report-agent --help`
+ * enumerates exactly `idle, working, blocked, unknown`, and a pane carries the state an
+ * external source published (`"agent":"<label>","agent_status":"blocked"` on a pane that
+ * read `unknown` a second earlier). So these four are herdr's own set, not ours.
+ *
+ * ⛔ `unknown` IS THE ABSENCE OF A SIGNAL, NOT A STATE OF THE SEAT. A tick that reads
+ * `unknown` is UNREADABLE — reported as such and counted as unmeasured — because the whole
+ * defect this task answers is a fleet that reads CALM when it is BLIND (Task 5.3).
+ */
+export const TICK_STATES = ["idle", "working", "blocked"] as const;
+export type TickState = (typeof TICK_STATES)[number];
+
+/**
+ * ⛔⛆ THE WRITE VOCABULARY AND THE READ VOCABULARY ARE NOT THE SAME, AND ONLY A READ-BACK
+ * FINDS IT. Measured 2026-09-16 on a fresh pane of my own, six writes and three repeats:
+ *
+ *   published --state working  → agent_status "working"
+ *   published --state blocked  → agent_status "blocked"
+ *   published --state idle     → agent_status "done"      ⬅ 3 of 3, with and without --seq
+ *   published --state unknown  → agent_status "unknown"
+ *
+ * herdr ACCEPTS `idle` (its own `--help` lists it) and STORES `done`. Nothing in the CLI
+ * says so: the write prints nothing and exits 0 either way. This is exactly what the
+ * receipt exists to catch, and it was caught by the read-back failing, not by reasoning.
+ *
+ * For the tick's purpose the two mean the same thing — a seat that is not working — so a
+ * `done` READS as `idle`, and a publish of `idle` is verified against `done`. The
+ * translation is named here rather than hidden in a comparison, so a herdr release that
+ * changes it fails a test instead of quietly inverting a verdict.
+ *
+ * ⚠ THE TWO DIRECTIONS ARE NOT THE SAME SET, AND THE `done` ENTRY IS NOT DEAD CODE — qa
+ * measured the asymmetry from the other side on herdr 0.9.0: `report-agent --state done`
+ * is REFUSED ("expected idle, working, blocked, or unknown"), so nothing we publish can
+ * produce it. It is still REACHABLE ON READ, which is the side `TICK_READS_AS` serves:
+ * `agent_status` is what a pane REPORTS, and herdr's own `agent wait --until` enumerates
+ * `idle, working, blocked, done, unknown`. A herdr-managed Claude session that finishes
+ * hands us `done` without anyone publishing it. So: refused on write, reachable on read,
+ * measured in both directions — do not delete this entry as unreachable.
+ */
+export const TICK_STORED_AS: Readonly<Record<TickState, string>> = Object.freeze({ idle: "done", working: "working", blocked: "blocked" });
+export const TICK_READS_AS: Readonly<Record<string, TickState>> = Object.freeze({ idle: "idle", done: "idle", working: "working", blocked: "blocked" });
+export type TickReading =
+  | { readable: true; state: TickState; source: string }
+  | { readable: false; why: string };
+
 /** Keystroke-shaped commands a transport must deliver to an interactive pane. */
 export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
 export type ControlCommand = (typeof CONTROL_COMMANDS)[number];
@@ -198,4 +245,23 @@ export interface Transport {
   sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }>;
 
   reapWedged(markers: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }>;
+
+  /**
+   * ⟨q-1c95f7d4⟩ 5.1 — OPTIONAL, AND ITS ABSENCE IS THE HONEST ANSWER FOR tmux.
+   *
+   * A transport implements `readTick` only when something OUTSIDE this process observes
+   * the seat and can be asked. tmux cannot: a pane is a terminal, and "a pid exists" is
+   * what `probe` already says. Declaring the method optional is what keeps `stall_check`
+   * from inventing a tick for a tmux seat and reading a fabricated calm — those seats keep
+   * the unmeasurable story they had (5.3).
+   */
+  readTick?(marker: TransportMarker): Promise<TickReading>;
+
+  /**
+   * ⟨q-1c95f7d4⟩ Task 1's open question, answered by measurement: THE PIPE RUNS BOTH WAYS.
+   * `coord-mcp` knows what herdr cannot infer — which seat holds which lane, whether a
+   * DONE: awaits a verdict, whether a seat is parked on a David decision — so a transport
+   * that can PUBLISH state to its external observer exposes it here.
+   */
+  publishTick?(marker: TransportMarker, state: TickState, opts?: { message?: string; source?: string }): Promise<{ ok: boolean; error?: string }>;
 }