agent-coord-mcp 0.26.24 → 0.26.26

package/src/tools/transport.ts

@@ -1,6 +1,5 @@
-import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+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";
@@ -685,163 +683,28 @@ export async function attachAgentTool(args: {
       agentId: args.agentId,
       transport: HERDR,
       target: marker.target,
-      pid: 0,
+      pid: marker.pid,
+      pidWhy: marker.pidWhy,
       rooms: marker.rooms,
       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 (existing && isPidAlive(existing.pid)) {
-    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

@@ -36,6 +36,16 @@
 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";
+// ⟨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,8 +255,26 @@ 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) {
+      // ⟨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;
     }
@@ -178,10 +283,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 +310,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 +451,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,

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";
@@ -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;
 
@@ -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;
   }