agent-coord-mcp 0.26.23 → 0.26.25

package/src/transports/herdr.ts

@@ -34,8 +34,18 @@
  *     same reason (identical evidence for a typo and a default).
  */
 import { spawnSync } from "node:child_process";
-import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker } from "./types.js";
-import { HERDR, targetOf } from "./types.js";
+import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
+import { HERDR, TICK_READS_AS, TICK_STORED_AS, targetOf } from "./types.js";
+// ⟨q-dc83023a⟩ The chip grammar and the pane-unsafe byte class are single-sourced in hooks/, shared
+// with both pushers. `hooks/` ships beside `dist/`, so these resolve the same when installed.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { PASTE_CHIP_RE, readReadyBox, readyProfile, refusalBeforeKeys, boxHoldsPayload, transcriptGained } from "../../hooks/submit.mjs";
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { neutralizeControls } from "../../hooks/control-bytes.mjs";
+
+/** Bracketed-paste markers (xterm mode 2004), which Claude Code and tmux `paste-buffer -p` both speak. */
+export const PASTE_START = "\x1b[200~";
+export const PASTE_END = "\x1b[201~";
 
 export type HerdrError = { code: string; message: string };
 export type HerdrResult = {
@@ -118,6 +128,20 @@ function processInfoOf(r: HerdrResult): ProcessInfo | undefined {
 }
 const LIVE_STATUSES = new Set(["idle", "working", "blocked", "done"]);
 
+/**
+ * ⟨q-15d763dc⟩ What a push did, so a caller can tell a message that is safe to try again from one
+ * that may already be sitting in the pane:
+ *   delivered         — verified: the ready box took it and the transcript shows it. The ONLY
+ *                       outcome a cursor may advance on.
+ *   held              — NO key was sent (no ready box, a draft, a menu, or the pane unreadable).
+ *                       Safe to retry.
+ *   typed-unconfirmed — the text was typed but did not show in the box; Enter was NOT sent.
+ *   pending           — the text is still in the box after every Enter.
+ *   unverified        — Enter was sent and the screen after it does not prove submission.
+ */
+export type PushOutcome = "delivered" | "held" | "typed-unconfirmed" | "pending" | "unverified";
+export type HerdrPushResult = { delivered: boolean; verified?: boolean; outcome?: PushOutcome; safeToRetry?: boolean; error?: string; enters?: number; unguarded?: boolean; busy?: boolean };
+
 export type HerdrTransportOptions = {
   run?: HerdrRunner;
   /** Milliseconds to wait before reading a pane back after typing. */
@@ -126,14 +150,75 @@ export type HerdrTransportOptions = {
   sleep?: (ms: number) => void;
   /** Lines of pane to read back when verifying a delivery. */
   readLines?: number;
+  /** Injectable marker-pid decision (tests); defaults to asking the kernel about pid 1. */
+  markerPid?: () => HerdrMarkerPid;
+  /**
+   * The environment `attach` reads its default pane from. Injectable because it is AMBIENT
+   * PROCESS STATE, and ambient state is the one input an injected runner does not cover.
+   *
+   * ⛔ MEASURED 2026-09-16, the day seats moved onto herdr: the attach test injected a scripted
+   * runner and still read the REAL `process.env.HERDR_PANE_ID`. Outside herdr the variable was
+   * absent and the test passed; inside a herdr pane it resolved to the gater's own pane
+   * (`wA6:p1`), the scripted runner had never heard of it, and the suite went red on every
+   * herdr-hosted tree for a reason unrelated to any diff. Stripping `HERDR_PANE_ID` alone — one
+   * variable at a time, six others left in place — was what turned it green.
+   */
+  env?: Record<string, string | undefined>;
 };
 
+/**
+ * ⟨q-abd88dd4⟩ — THE PID A HERDR MARKER CARRIES, chosen for the readers that CANNOT be patched.
+ *
+ * A herdr seat has no pusher, so its marker used to carry pid 0. Every server build from before
+ * the herdr transport (0.19.1, kit 0.26.19, published 0.26.22 — reproduced in a throwaway bus
+ * against each) decides marker liveness as `isPidAlive(marker.pid)` for everything but
+ * `tmux-push-remote`, and `isPidAlive(0)` is false, so ONE ordinary read (`list_agents`,
+ * `status`, `stall_check`, `send_command`) DELETES the marker. A mixed-build fleet deafens its
+ * herdr seats as a side effect of looking at the roster.
+ *
+ * pid 1 is kept by all three: it always exists, so `isPidAlive(1)` is true. Their signal paths,
+ * enumerated by qa across all three on its gate: kit 0.26.19 and published 0.26.22 gate
+ * `detach_agent`'s SIGTERM on `isPusherProcess(marker.pid)`, which reads the process COMMAND, so they
+ * never signal launchd whatever uid they run as. Only 0.19.1's detach is unguarded (`isPidAlive`
+ * then `process.kill(marker.pid, "SIGTERM")`, reachable from `detach_agent`, `unregister` and
+ * `rename_agent`), and it enforces identity, so its caller must be bound as that herdr seat. As a
+ * non-root process that kill gets EPERM — measured `killed:false`, launchd untouched. The seat's own
+ * server pid would have been kept by all three as well, and 0.19.1's unguarded detach would have
+ * SIGTERMed that seat's MCP server; that shape is rejected.
+ *
+ * ⛔ SO pid 1 IS WRITTEN ONLY WHEN THIS PROCESS COULD NOT SIGNAL IT, asked of the kernel with
+ * signal 0 rather than inferred from a uid: as root, or in a container where pid 1 is our own
+ * user's process (often the server itself), `kill(1, 0)` succeeds and an old reader running
+ * alongside could SIGTERM init. There the marker falls back to pid 0 and says why — an old
+ * reader then deletes it, which is deafness, and deafness is recoverable where a signal to init
+ * is not. RESIDUAL, stated as narrowly as it is: a 0.19.1-era server, running as ROOT, bound as
+ * the herdr seat's OWN identity, calling detach, unregister or rename, reaches init. Nothing a
+ * marker says can remove a privilege its reader holds.
+ *
+ * The CURRENT build never reads this pid as liveness: a herdr marker is live exactly when herdr
+ * says its pane exists (`isMarkerLive`), and nothing signals it (`detach_agent` removes the
+ * marker, `markerHoldsLiveProcess` answers false).
+ */
+export type HerdrMarkerPid = { pid: 0 | 1; why: string };
+export function herdrMarkerPid(kill: (pid: number, signal: 0) => unknown = (p, s) => process.kill(p, s)): HerdrMarkerPid {
+  try {
+    kill(1, 0);
+    return { pid: 0, why: "this process may signal pid 1 (root, or a container whose pid 1 is ours), so pid 1 is not safe to advertise; pre-herdr readers will reap this marker" };
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "EPERM") return { pid: 1, why: "pid 1 exists and this process may not signal it, so pre-herdr readers keep the marker and their detach cannot signal it" };
+    return { pid: 0, why: `kill(1, 0) answered ${code ?? "an unexpected error"}, not EPERM — pid 1 not advertised` };
+  }
+}
+
 export class HerdrTransport implements Transport {
   readonly kind: TransportKind = HERDR;
   #run: HerdrRunner;
   #settleMs: number;
   #sleep: (ms: number) => void;
   #readLines: number;
+  #markerPid: () => HerdrMarkerPid;
+  #env: Record<string, string | undefined>;
 
   constructor(opts: HerdrTransportOptions = {}) {
     this.#run = opts.run ?? defaultHerdrRunner;
@@ -143,7 +228,9 @@ export class HerdrTransport implements Transport {
     // 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;
+    this.#readLines = opts.readLines ?? 40;
+    this.#markerPid = opts.markerPid ?? (() => herdrMarkerPid());
+    this.#env = opts.env ?? process.env;
   }
 
   /** Is herdr on this host AND is its server running? Both, or the reason. */
@@ -168,7 +255,7 @@ export class HerdrTransport implements Transport {
   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;
+    let target = args.target ?? this.#env.HERDR_PANE_ID;
     if (!target) {
       const cur = this.#run(["pane", "current"]);
       target = paneOf(cur)?.pane_id;
@@ -178,10 +265,12 @@ export class HerdrTransport implements Transport {
     }
     const got = this.#run(["pane", "get", target]);
     if (!got.ok) throw new Error(`herdr pane '${target}' not found: ${got.error?.message ?? got.stderr}`);
+    const markerPid = this.#markerPid();
     return {
       agentId: args.agentId,
       transport: HERDR,
-      pid: 0,
+      pid: markerPid.pid,
+      pidWhy: markerPid.why,
       target,
       tmuxTarget: target,
       since: Date.now(),
@@ -203,40 +292,108 @@ export class HerdrTransport implements Transport {
    * 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.
+   *
+   * ⟨q-dc83023a⟩ A DELIVERY IS A BRACKETED PASTE BY DEFAULT. `send-text` types keystrokes and
+   * herdr writes them in 1022-byte chunks; Claude Code v2.1.273 folds each large chunk into a
+   * `[Pasted text #N]` chip and, on submit, KEPT ONLY THE LAST CHUNK — a 2668-byte message
+   * arrived as its final 624 bytes, the PR, sha and gate gone. Wrapped in paste markers, the
+   * same bytes arrived whole (measured at 2668 B, 5 KB multi-line and 20 KB). The body is
+   * neutralised first so it can never carry the closing marker itself (⟨q-e5cb3538⟩).
+   * `paste: false` is for control commands only: a slash command must arrive as typing.
    */
-  async push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string; enters?: number; verified?: boolean }> {
+  async push(marker: TransportMarker, text: string, opts: { paste?: boolean } = {}): Promise<HerdrPushResult> {
     const avail = this.availability();
-    if (!avail.available) return { delivered: false, error: avail.reason };
+    if (!avail.available) return { delivered: false, outcome: "held", safeToRetry: true, 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}` };
+    if (!target) return { delivered: false, outcome: "held", safeToRetry: true, error: "no target recorded on the marker" };
+    const payload = opts.paste === false ? text : `${PASTE_START}${neutralizeControls(text)}${PASTE_END}`;
     const enterKey = herdrKeyName("enter");
-    if (!enterKey.ok) return { delivered: false, error: enterKey.error };
+    if (!enterKey.ok) return { delivered: false, outcome: "held", safeToRetry: true, error: enterKey.error };
+    if (readyProfile().profile === "none") return this.#pushUnguarded(target, text, payload, enterKey.key);
+
+    // ⟨q-15d763dc⟩ BEFORE ANY KEY: the screen must be Claude Code's ready, empty input box. The text
+    // is held as firmly as the Enter — a digit typed into an open dialog selects an option.
+    const before = readReadyBox(this.#screen(target));
+    const refusal = refusalBeforeKeys(before);
+    if (refusal) return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `held, nothing typed into ${target}: ${refusal}` };
+
+    const typed = this.#run(["pane", "send-text", target, payload]);
+    if (!typed.ok) return { delivered: false, verified: false, outcome: "held", safeToRetry: true, error: `send-text to ${target} refused: ${typed.error?.message ?? typed.stderr}` };
+    this.#sleep(this.#settleMs);
+    let box = readReadyBox(this.#screen(target));
+    if (!boxHoldsPayload(box, text)) {
+      return { delivered: false, verified: false, outcome: "typed-unconfirmed", safeToRetry: false, error: `typed into ${target}, but the text did not show in the input box (${box.ready ? "box holds something else" : box.reason}) — Enter NOT sent` };
+    }
     let enters = 0;
     for (let attempt = 0; attempt < 2; attempt++) {
+      // Every Enter follows a read that saw THIS payload in the ready box, never a stale one.
       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 };
+      if (!pressed.ok) return { delivered: false, verified: false, outcome: "typed-unconfirmed", safeToRetry: false, error: `send-keys enter to ${target} refused: ${pressed.error?.message ?? pressed.stderr}`, enters };
+      enters++;
+      this.#sleep(this.#settleMs);
+      box = readReadyBox(this.#screen(target));
+      if (transcriptGained(before, box, text)) return { delivered: true, verified: true, outcome: "delivered", safeToRetry: false, enters, busy: box.ready ? box.busy ?? undefined : undefined };
+      if (boxHoldsPayload(box, text)) continue;
+      return { delivered: false, verified: false, outcome: "unverified", safeToRetry: false, enters, error: `enter sent to ${target}, but the screen after it does not show the message submitted (${box.ready ? (box.draft ? "the box holds other text" : "the box is empty and the transcript gained no line carrying it") : box.reason})` };
+    }
+    return { delivered: false, verified: true, outcome: "pending", safeToRetry: false, enters, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+  }
+
+  /** The screen, styled, so the ready-box reader can tell a ghost suggestion from a draft. null = unreadable. */
+  #screen(target: string): string | null {
+    const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(this.#readLines), "--format", "ansi"]);
+    return read.ok ? read.stdout : null;
+  }
+
+  /**
+   * AGENT_COORD_READY_PROFILE=none, chosen by whoever started this process: #357's push, with no
+   * readiness check. Reported `unguarded`, and an unreadable screen still never counts as verified.
+   */
+  #pushUnguarded(target: string, text: string, payload: string, enter: string): HerdrPushResult {
+    const typed = this.#run(["pane", "send-text", target, payload]);
+    if (!typed.ok) return { delivered: false, unguarded: true, outcome: "held", safeToRetry: true, error: `send-text to ${target} refused: ${typed.error?.message ?? typed.stderr}` };
+    let enters = 0;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const pressed = this.#run(["pane", "send-keys", target, enter]);
+      if (!pressed.ok) return { delivered: false, unguarded: true, outcome: "typed-unconfirmed", safeToRetry: 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 };
+      if (pending === false) return { delivered: true, verified: true, unguarded: true, outcome: "delivered", safeToRetry: false, enters };
+      if (pending === null) return { delivered: false, verified: false, unguarded: true, outcome: "unverified", safeToRetry: false, enters, error: `enter sent to ${target}, but the pane could not be read back to verify it` };
     }
-    return { delivered: false, enters, verified: true, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+    return { delivered: false, verified: true, unguarded: true, outcome: "pending", safeToRetry: false, enters, 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)?
+   * Read the pane back: is the typed text still sitting in the INPUT (unsubmitted)?
    * true = pending · false = submitted · null = could not read (unverified, not failed).
+   *
+   * ⟨q-dc83023a⟩ THE INPUT IS THE PROMPT LINE, NOT THE LAST LINE. Claude Code draws a border,
+   * a footer and hints ("paste again to expand") BELOW its `❯` input, so the last non-empty
+   * line is never the input and the old last-line check answered "submitted" for a message
+   * still sitting there. The prompt line is pending when it shows a paste chip or the start
+   * of what was typed (a long first line wraps, so either may be a prefix of the other).
+   *
+   * NO PROMPT LINE → null (UNVERIFIED), never the last-line reading: that reading was measured
+   * to answer "submitted" for text still sitting in Claude's input, so falling back to it would
+   * let a changed Claude version, an open dialog or a read mid-render verify silently again
+   * (the coordinator's condition on ⟨q-dc83023a⟩, from worker-2). What a caller does with an
+   * unverified delivery is ⟨q-15d763dc⟩.
    */
   #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);
+    const prompt = [...lines].reverse().find((l) => /^\s*❯/.test(l));
+    if (prompt !== undefined) {
+      const content = prompt.replace(/^\s*❯\s?/, "").trim();
+      if (!content) return false;
+      if (PASTE_CHIP_RE.test(content)) return true;
+      return firstLine.startsWith(content) || content.startsWith(firstLine);
+    }
+    return null;
   }
 
   /**
@@ -276,7 +433,8 @@ export class HerdrTransport implements Transport {
    * 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}`);
+    const r = await this.push(marker, `/${cmd}`, { paste: false });
+    // push reports delivered only when verified (⟨q-15d763dc⟩), so `delivered` is the whole test here.
     if (!r.delivered) return { ok: false, error: r.error ?? "control not delivered", enters: r.enters };
     return {
       ok: true,
@@ -285,6 +443,80 @@ export class HerdrTransport implements Transport {
     };
   }
 
+  /**
+   * ⟨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.

package/src/transports/index.ts

@@ -14,7 +14,7 @@ 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";
+export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, herdrMarkerPid, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult, type HerdrMarkerPid } from "./herdr.js";
 
 let host: TmuxHost | undefined;
 

package/src/transports/types.ts

@@ -87,6 +87,11 @@ export type TransportMarker = {
   target?: string;
   /** The original field. Still written. See `target`. */
   tmuxTarget?: string;
+  /**
+   * ⟨q-abd88dd4⟩ herdr only: why `pid` holds what it holds (see `herdrMarkerPid`). A herdr
+   * marker's pid is addressed to PRE-HERDR readers and is never liveness for this build.
+   */
+  pidWhy?: string;
   since: number;
   /**
    * Remote pushers run on a different machine; the local pid is meaningless,
@@ -154,6 +159,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 +250,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 }>;
 }