agent-coord-mcp 0.26.25 → 0.26.26

package/hooks/tmux-pusher.mjs

@@ -1,971 +0,0 @@
-#!/usr/bin/env node
-/**
- * tmux-pusher.mjs
- *
- * Long-running daemon that watches an agent's coord inbox (and optionally the
- * shared room) and types new messages into a tmux pane running an interactive
- * CLI agent. Works with any line-driven agent CLI: Claude Code, Aider, codex,
- * gemini-cli, opencode, etc.
- *
- * Required env:
- *   AGENT_COORD_ID            agentId registered with the MCP
- *   AGENT_COORD_TMUX_TARGET   tmux target, e.g. "coord-frontend:agent.0"
- *
- * Optional env:
- *   AGENT_COORD_DIR           override state dir (default ~/agent-coord)
- *   AGENT_COORD_INCLUDE_ROOM  "1" to also inject shared-room messages
- *   AGENT_COORD_ALLOWLIST     comma-separated peer agentIds to accept
- *                             (default: accept all)
- *   AGENT_COORD_DEBOUNCE_MS   coalesce window for bursts (default 1000)
- *   AGENT_COORD_POLL_MS       fallback poll interval (default 1000)
- *   AGENT_COORD_RETRY_MAX_MS  backoff ceiling for retrying messages the pane
- *                             refused (default 60000)
- *   AGENT_COORD_GIVEUP_AFTER  consecutive failed flushes before push is
- *                             SUSPENDED and the agent is left to read its own
- *                             traffic via read_messages (default 5)
- *   AGENT_COORD_TARGET_GRACE  missed pane probes before self-exit (default 3)
- *   AGENT_COORD_MAX_QUEUE_MS  max time routine (channel) traffic may queue
- *                             without an urgent trigger before it flushes as
- *                             a digest (default 15000 = 15s; 0 disables)
- *
- * Safety:
- *   - drops messages where from === AGENT_COORD_ID (no self-echo)
- *   - drops messages whose text starts with "/" (avoid injected slash commands),
- *     EXCEPT control-flagged messages carrying an allowlisted command
- *     (/clear, /compact, /reload-skills) sent via the MCP `send_command` tool — those are
- *     injected RAW (no banner/prefix) so the CLI runs them as slash commands
- *   - if allowlist set, drops messages from peers not in it
- *   - serializes tmux sends so two batches never overlap
- *
- * Cursor: shares ~/agent-coord/cursors/<id>.json with the MCP server, so the
- * agent calling read_messages won't see anything the pusher already delivered.
- * The cursor advances ONLY past messages the pane actually accepted: inject
- * reports back what it could not deliver, and a batch with any undelivered
- * message commits nothing and retries just that remainder (backing off to
- * AGENT_COORD_RETRY_MAX_MS). Delivery is therefore at-least-once, never
- * at-most-once — a refusing pane holds traffic, it does not drain it. That is
- * load-bearing: committing the batch whenever inject merely returned meant a
- * shell-parked pane, a slow paste, an unrecognised prompt or a lost Enter
- * silently discarded messages the sender had been told were delivered, and
- * read_messages could not see them either.
- *
- * A pane can also be PERMANENTLY unpushable — in the field that is the common
- * failure, not the rare one (one fleet: 1,001 of 1,004 push failures were a
- * single agent whose TUI never matched PROMPT_PATTERN). After
- * AGENT_COORD_GIVEUP_AFTER consecutive failures the pusher suspends and rewinds
- * to the on-disk cursor, so the agent simply reads its own inbox. Note the
- * division this rests on: receipts/ record whether a PUSH landed, cursors/
- * record whether the AGENT consumed. A clean receipt run is evidence of
- * delivery, never of receipt — an agent can be fully caught up with every push
- * to it having failed.
- *
- * Do NOT enable peek-coord.mjs Stop/UserPromptSubmit hooks for the same agent
- * while this daemon runs — both consume the same cursor and would race.
- *
- * Caveats:
- *   - PEER MESSAGES paste into whatever pane state exists. If you're mid-typing
- *     in the same pane, your buffer gets corrupted. Run the receiving agent in
- *     a dedicated pane you don't normally edit in.
- *   - CONTROL COMMANDS (/clear, /compact, /reload-skills) are the exception: since they paste
- *     RAW, a pane that is busy or holds an unsent draft would either queue them
- *     behind a running turn or append them to the draft and ship the result to
- *     the model as ordinary text — both observed live, both reporting
- *     delivery:"confirmed". So control submission is CONDITIONAL: it waits
- *     (bounded) for a busy pane to go idle, refuses to paste onto a draft, and
- *     verifies via capture-pane that the command left the input. An unverified
- *     submission reports delivery:"pending" with a reason, never "confirmed".
- *     See hooks/submit.mjs, shared with scripts/coord-pusher.mjs.
- *   - CLEANUP: never `pkill -f tmux-pusher.mjs` — the pattern matches EVERY
- *     pusher on the bus, and one agent's test-rig cleanup doing exactly that
- *     silently detached all four live agents (2026-07-28). attach_agent puts
- *     `--agent <id>` in argv so a pattern kill can be scoped to one agent
- *     (`pkill -f "tmux-pusher.mjs --agent <id>"`); better still, use
- *     detach_agent or the pid file — both target the exact pid.
- */
-
-import {
-  existsSync,
-  readFileSync,
-  writeFileSync,
-  appendFileSync,
-  renameSync,
-  mkdirSync,
-  unlinkSync,
-  watch,
-} from "node:fs";
-import { readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { fileURLToPath } from "node:url";
-import path from "node:path";
-import { spawn, spawnSync } from "node:child_process";
-import { effectiveTier, isGateRunnerRole, TierQueue, formatBatch } from "./tier.mjs";
-import { isCi } from "./roles.mjs";
-import { mergeTransportMarker } from "./marker.mjs";
-import { readPushCursor, writePushCursor } from "./push-cursor.mjs";
-import { priorDeliveries, replayInfo } from "./replay.mjs";
-import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl, readyProfileStartupLine } from "./submit.mjs";
-
-const AGENT_ID = process.env.AGENT_COORD_ID;
-const TMUX_TARGET = process.env.AGENT_COORD_TMUX_TARGET;
-if (!AGENT_ID) die("AGENT_COORD_ID is required");
-if (!TMUX_TARGET) die("AGENT_COORD_TMUX_TARGET is required");
-
-const ROOT = process.env.AGENT_COORD_DIR || path.join(homedir(), "agent-coord");
-const INCLUDE_ROOM = process.env.AGENT_COORD_INCLUDE_ROOM === "1";
-// Default channel + watch registry — declared up here so the hoisted channel
-// helpers, called from the top-level checkOnce(), don't trip the const TDZ.
-const DEFAULT_ROOM = "general";
-const watchedRooms = new Set();
-const ALLOWLIST = (process.env.AGENT_COORD_ALLOWLIST || "")
-  .split(",")
-  .map((s) => s.trim())
-  .filter(Boolean);
-const DEBOUNCE_MS = parseInt(process.env.AGENT_COORD_DEBOUNCE_MS || "1000", 10);
-const POLL_MS = parseInt(process.env.AGENT_COORD_POLL_MS || "1000", 10);
-// Ceiling for the undelivered-retry backoff (see nextRetryDelay). A permanently
-// refusing pane must keep retrying — the traffic is held, not dropped — but at
-// a rate that costs one capture-pane a minute rather than one a second.
-const RETRY_MAX_MS = parseInt(process.env.AGENT_COORD_RETRY_MAX_MS || "60000", 10);
-// Consecutive missed pane probes before we conclude the target is gone and
-// self-exit. A small grace rides out transient tmux-server hiccups.
-const TARGET_GRACE = parseInt(process.env.AGENT_COORD_TARGET_GRACE || "3", 10);
-// Delivery tiers: only push-now traffic (BLOCKER/DAVID_DECISION/GO:/
-// trusted SCOPE:/DONE-to-gate, controls, server-flagged reminders) wakes the
-// agent; everything else queues unread and rides the next push as a coalesced
-// digest. AGENT_COORD_TIERS=0 restores legacy push-everything.
-const TIERS_ENABLED = process.env.AGENT_COORD_TIERS !== "0";
-// Max-age flush: routine traffic never waits longer than this for an urgent
-// trigger — once the oldest queued message is overdue, the backlog flushes as
-// a routine-only digest. Bounds the silent-fleet failure mode where FYI:/DONE:
-// chatter queues forever because nothing urgent ever arrives. Only channel
-// traffic queues (DMs are push-now), so the default is short.
-const MAX_QUEUE_MS = parseInt(process.env.AGENT_COORD_MAX_QUEUE_MS || "15000", 10);
-// Gate runners (QA/coordinator) receive DONE: as push-now; countersigned
-// SCOPE: changes are honored only from these trusted ids. Re-resolved from
-// the registry every 30s so a role change doesn't strand a stale pusher;
-// AGENT_COORD_GATE_RUNNER=1|0 overrides in both directions.
-let tierCtx = { enabled: TIERS_ENABLED, gateRunner: false, ci: false, trustedSenders: new Set() };
-function refreshTierCtx() {
-  let gateRunner = false;
-  let ci = false;
-  const trusted = new Set();
-  try {
-    const reg = JSON.parse(readFileSync(path.join(ROOT, "agents.json"), "utf8"));
-    for (const [id, entry] of Object.entries(reg ?? {})) {
-      // Pass the whole entry: the frozen roleId lives beside `role`, and
-      // reading only the display string would throw the identity away.
-      if (isGateRunnerRole(entry)) trusted.add(id);
-      if (id === AGENT_ID) ci = isCi(entry);
-    }
-    gateRunner = trusted.has(AGENT_ID);
-  } catch {
-    // No registry yet — conservative default (not a gate runner, not ci).
-  }
-  const env = process.env.AGENT_COORD_GATE_RUNNER;
-  if (env === "1" || env === "true") gateRunner = true;
-  if (env === "0" || env === "false") gateRunner = false;
-  // AGENT_COORD_GATE_RUNNER must not flip ci — that would look like a
-  // verdict grant. Express-lane wake is roleId === ci only.
-  if (gateRunner !== tierCtx.gateRunner || ci !== tierCtx.ci) {
-    process.stderr.write(`[tmux-pusher] gate-runner resolved: ${gateRunner} ci: ${ci}\n`);
-  }
-  tierCtx = { enabled: TIERS_ENABLED, gateRunner, ci, trustedSenders: trusted };
-}
-refreshTierCtx();
-setInterval(refreshTierCtx, 30_000).unref();
-
-const SAFE_ID = AGENT_ID.replace(/[^a-zA-Z0-9._-]/g, "_");
-const INBOX_FILE = path.join(ROOT, "inbox", `${SAFE_ID}.jsonl`);
-const CURSOR_FILE = path.join(ROOT, "cursors", `${SAFE_ID}.json`);
-
-/*
- * THE PUSH CURSOR IS NOT THE READ CURSOR.
- *
- * These were one file. The pusher advanced `roomOffsets[chan]` the moment a
- * paste was DEEMED submitted, and `read_messages` reads the same offsets — so a
- * paste that never reached the pane still marked the message consumed. The
- * message was then unreachable by every route: not in the pane, and skipped by
- * the reader.
- *
- * That is today's parent class — a failure path returning a plausible success —
- * with one difference that makes it worse than every other instance: this one
- * WRITES THE SUCCESS INTO DURABLE STATE. The others produced a wrong reading;
- * this destroys the evidence that the reading was wrong.
- *
- * Measured on a consumer fleet: an agent's cursor sat past a peer's
- * `DONE: merged #<n>` at line 1107 of that room's log — a ROOM post, so its
- * inbox was correctly empty and its `gh` current. Everything looked fine.
- *
- * Separating them does NOT make delivery reliable. It converts SILENT LOSS into
- * mere NON-DELIVERY: the message stays unread in the read cursor, so
- * `read_messages` still serves it and the failure becomes visible. Cheapest
- * first, and it is the half that stops data loss rather than a stall.
- *
- * The cost is duplication, deliberately: a message pasted into the pane may
- * also be served by `read_messages`. At-least-once with a visible duplicate
- * beats at-most-once with an invisible hole — the same ruling as the event
- * subscriptions' delivery contract.
- */
-const PUSH_CURSOR_FILE = path.join(ROOT, "cursors", `${SAFE_ID}.push.json`);
-const TRANSPORT_FILE = path.join(ROOT, "transports", `${SAFE_ID}.json`);
-// Out-of-band delivery receipts: stamped AFTER a message is typed into the
-// pane, so the sender can poll for proof of delivery without the receipt ever
-// entering any agent's context. Mirrors RECEIPTS_DIR in src/store.ts.
-const RECEIPTS_FILE = path.join(ROOT, "receipts", `${SAFE_ID}.jsonl`);
-const BUFFER_NAME = `coord-${SAFE_ID}`;
-// Newest mtime across this script AND its sibling hooks modules, sampled once
-// at startup — an upgrade to any of them afterwards leaves this value behind,
-// which is exactly what doctor's stale-pusher-script check compares against.
-// The entry file alone is not enough: control submission lives in submit.mjs
-// and tiering in tier.mjs/roles.mjs, so a fix touching only an import would
-// leave a single-file stamp unchanged and a still-running pusher on the old
-// code would read as fresh. Scanning the whole dir over-covers (a hooks file
-// we never import can flag us stale) — that is the safe direction: a spurious
-// re-attach is loud and cheap, a false green silently invalidates the rollout
-// verification of every pusher-side fix.
-const SCRIPT_MTIME = (() => {
-  try {
-    const dir = path.dirname(fileURLToPath(import.meta.url));
-    let newest;
-    for (const f of readdirSync(dir)) {
-      if (!f.endsWith(".mjs")) continue;
-      const m = statSync(path.join(dir, f)).mtimeMs;
-      if (newest === undefined || m > newest) newest = m;
-    }
-    return newest;
-  } catch {
-    return undefined;
-  }
-})();
-
-mkdirSync(path.dirname(CURSOR_FILE), { recursive: true });
-mkdirSync(path.dirname(TRANSPORT_FILE), { recursive: true });
-mkdirSync(path.dirname(RECEIPTS_FILE), { recursive: true });
-
-// Confirm tmux target exists at startup so we fail loudly instead of silently.
-// `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-// DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-// ago, so the probe had ZERO discriminating power and reported every dead
-// pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-// tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-// Positive control, both directions: bogus target -> has-session exit 1,
-// display-message exit 0; live pane -> both exit 0.
-const probe = spawnSync("tmux", ["has-session", "-t", TMUX_TARGET]);
-if (probe.status !== 0) {
-  die(`tmux target '${TMUX_TARGET}' not found: ${(probe.stderr ?? "").toString().trim()}`);
-}
-
-let pending = [];
-let debounceTimer = null;
-let sending = false;
-let targetMisses = 0;
-
-// Cursor IO lives in ./push-cursor.mjs so it can be EXERCISED — inline here,
-// the only thing a test could reach was the source text.
-function readCursor() {
-  return readPushCursor(ROOT, SAFE_ID);
-}
-
-function writeCursor(c) {
-  writePushCursor(ROOT, SAFE_ID, c);
-}
-
-function readJsonl(file) {
-  if (!existsSync(file)) return [];
-  return readFileSync(file, "utf8")
-    .split("\n")
-    .filter(Boolean)
-    .map((l) => {
-      try {
-        return JSON.parse(l);
-      } catch {
-        return null;
-      }
-    })
-    .filter(Boolean);
-}
-
-// Allowlisted control commands the bus may type into this CLI. Mirrors
-// CONTROL_COMMANDS in src/tools/transport.ts and scripts/coord-pusher.mjs
-// (test/allowlist-parity.test.mjs locks the three); kept tiny + literal so a bugged/compromised
-// sender can't smuggle an arbitrary slash command onto the RAW submit path.
-// ⚠ THIS SET IS THE GATE. It used to be backed by a second check that dropped any
-// text starting with "/"; that check was removed in ⟨q-f14692ca⟩ because it silently
-// discarded legitimate messages and never saw the multi-line shape it was aimed at.
-// Membership here, plus bracketed paste on the peer path, is now the whole defence.
-const CONTROL_COMMANDS = new Set(["/clear", "/compact", "/reload-skills"]);
-
-// Shells we refuse to inject into: if the pane's foreground command is one of
-// these, the agent CLI has exited and typing would run pasted text as commands.
-const SHELL_COMMANDS = new Set(["bash", "zsh", "sh", "fish", "dash", "ksh"]);
-
-// Foreground command of the target pane, or null if it can't be determined
-// (in which case we do NOT block — fall back to the bracketed-paste protection).
-function paneCurrentCommand() {
-  const r = spawnSync("tmux", [
-    "display-message",
-    "-p",
-    "-t",
-    TMUX_TARGET,
-    "#{pane_current_command}",
-  ]);
-  if (r.status !== 0) return null;
-  return (r.stdout ?? "").toString().trim() || null;
-}
-
-function isControl(m) {
-  return (
-    !!m &&
-    m.control === true &&
-    typeof m.text === "string" &&
-    CONTROL_COMMANDS.has(m.text.trim())
-  );
-}
-
-function shouldInject(m) {
-  if (!m || m.from === AGENT_ID) return false;
-  if (ALLOWLIST.length > 0 && !ALLOWLIST.includes(m.from)) return false;
-  // Authorized control command — injected RAW later, so the allowlist in
-  // `isControl` is the gate that matters. Checked first and unchanged.
-  if (isControl(m)) return true;
-
-  // ⛔ THE SLASH DROP USED TO LIVE HERE AND IT IS GONE ON PURPOSE (⟨q-f14692ca⟩).
-  //
-  // It returned false for any text starting with "/", which SILENTLY discarded
-  // the message: the sender was told nothing, and `collectSource` advances the
-  // offset past rejected lines, so it was never retried either. Measured in an
-  // isolated pane: a plain message and a trailing message both arrived, the
-  // slash-leading one between them did not, and the pusher log said nothing.
-  //
-  // AND IT WAS PROTECTING NOTHING THAT IS NOT ALREADY PROTECTED TWICE, measured
-  // rather than reasoned:
-  //   1. `formatBatch` prefixes every peer line with `  [DM hh:mm from] `, so a
-  //      single-line "/foo" reaches the pane with ZERO lines starting with "/" —
-  //      it is chat text, not a command.
-  //   2. Ordinary batches paste with `bracketed = true`, which makes the whole
-  //      payload inert: embedded newlines cannot submit a line or smuggle a
-  //      "/command". That is the defence that actually covers the multi-line
-  //      case, which this check never caught — `trimStart()` only ever examined
-  //      the FIRST line, so "opener\n/clear" passed straight through it.
-  //
-  // So the old guard was wrong in both directions at once: it dropped safe
-  // single-line messages, and it did not see the multi-line shape it was aimed
-  // at. Removing it restores delivery; the protection that matters is the
-  // allowlist above plus bracketed paste, and BOTH are pinned by tests in
-  // test/slash-message-delivery.test.mjs. ⚠ If anyone makes the peer path paste
-  // raw, those tests fail — which is the price of not having this check.
-  return true;
-}
-
-// In-memory delivery ledger. `stagedOffsets` marks how far we've COLLECTED
-// (prevents double-collection across polls); the on-disk cursor — shared
-// with read_messages — advances only after a batch is actually pasted. A
-// crash/SIGTERM/pane-death between the two rewinds to the on-disk cursor, so
-// queued-but-undelivered traffic is redelivered on restart (at-least-once),
-// never lost. Routine messages wait in tierQueue until a push-now trigger
-// coalesces them; their offset commits travel in pendingCommits alongside.
-const stagedOffsets = {};
-const tierQueue = new TierQueue({ maxAgeMs: TIERS_ENABLED ? MAX_QUEUE_MS : 0 });
-let pendingCommits = [];
-
-function collectSource(label, file, cursorKey, cur, staged) {
-  const all = readJsonl(file);
-  const off = Math.max(cur[cursorKey] ?? 0, stagedOffsets[cursorKey] ?? 0);
-  const fresh = all.slice(off);
-  if (fresh.length === 0) return;
-  for (const m of fresh) {
-    if (shouldInject(m)) {
-      // The channel tag lives in `tag`, not `kind`. A stored Message carries
-      // its own `kind` ("decision"/"status"/"chatter" — retention weight);
-      // sharing the name meant a room post tagged kind:"decision" (what the
-      // README recommends for GOs and verdicts) overwrote the channel tag and
-      // rendered as `[decision …]` instead of `[#general …]`, breaking
-      // injectLine's parse contract. Distinct names remove the collision at
-      // the source; assignment still follows the spread so a sender cannot
-      // smuggle a `tag` in either.
-      const tagged = { ...m, tag: label };
-      // Assigned after the spread so a sender can't smuggle a tier field in.
-      tagged.tier = effectiveTier(tagged, tierCtx);
-      staged.msgs.push(tagged);
-    }
-  }
-  const newOff = off + fresh.length;
-  stagedOffsets[cursorKey] = newOff;
-  // Offsets are absolute and applied monotonically, so re-applying on a
-  // flush retry is harmless.
-  staged.commits.push((c) => {
-    c[cursorKey] = Math.max(c[cursorKey] ?? 0, newOff);
-  });
-}
-
-// Collect one channel against its per-channel offset (general → roomOffset,
-// others → roomOffsets[chan]); tag collected lines with the channel name.
-function collectRoomChannel(chan, cur, staged) {
-  const c = normalizeRoom(chan);
-  const all = readJsonl(roomFile(c));
-  const off = Math.max(getRoomOffset(cur, c), stagedOffsets[`room:${c}`] ?? 0);
-  const fresh = all.slice(off);
-  if (fresh.length === 0) return;
-  for (const m of fresh) {
-    if (shouldInject(m)) {
-      const tagged = { ...m, tag: `room #${c}` }; // see channel-tag note above
-      tagged.tier = effectiveTier(tagged, tierCtx);
-      staged.msgs.push(tagged);
-    }
-  }
-  const newOff = off + fresh.length;
-  stagedOffsets[`room:${c}`] = newOff;
-  staged.commits.push((cc) => setRoomOffset(cc, c, Math.max(getRoomOffset(cc, c), newOff)));
-}
-
-// Fold accumulated offset commits into the on-disk cursor. Called from the
-// flush success path (delivery confirmed) and for junk-only batches.
-function commitOffsets(commits) {
-  if (commits.length === 0) return;
-  const cur = readCursor();
-  for (const c of commits) c(cur);
-  writeCursor(cur);
-}
-
-function checkOnce() {
-  // While suspended, collect NOTHING: the on-disk cursor is the sole record of
-  // what this agent still owes, and read_messages is serving it. Collecting
-  // would re-stage messages we cannot deliver, and — because offsets are
-  // absolute and applied with Math.max — a single later success would leapfrog
-  // the cursor past them and destroy exactly what the suspension protected.
-  if (pushSuspended) {
-    if (Date.now() - suspendedAt < RETRY_MAX_MS) return;
-    resumePush();
-  }
-  const cur = readCursor();
-  const staged = { msgs: [], commits: [] };
-  collectSource("DM", INBOX_FILE, "inboxOffset", cur, staged);
-  if (INCLUDE_ROOM) {
-    // Tail every channel the agent has joined. checkOnce runs on each poll, so
-    // channels joined after startup are picked up automatically.
-    for (const chan of joinedRooms()) {
-      collectRoomChannel(chan, cur, staged);
-      watchRoom(chan);
-    }
-  }
-  pendingCommits.push(...staged.commits);
-  if (
-    staged.msgs.length === 0 &&
-    tierQueue.size() === 0 &&
-    pending.length === 0 &&
-    !sending &&
-    pendingCommits.length > 0
-  ) {
-    // Everything fresh was filtered (self/allowlist/slash) and nothing is
-    // queued or in flight — fold the offsets forward now instead of leaving
-    // junk to block until a future push.
-    commitOffsets(pendingCommits);
-    pendingCommits = [];
-    return;
-  }
-  // Tiered delivery: push only when the fresh batch contains a push-now
-  // trigger. A routine-only backlog stays queued (on-disk cursor untouched)
-  // so an idle agent is never woken — it rides the digest of the next trigger,
-  // or flushes on its own once the oldest queued message exceeds MAX_QUEUE_MS.
-  const now = Date.now();
-  const batch = tierQueue.ingest(staged.msgs, now) ?? tierQueue.flushOverdue(now);
-  if (!batch) return;
-  pending.push(...batch);
-  scheduleFlush();
-}
-
-function scheduleFlush(delayMs = DEBOUNCE_MS) {
-  if (debounceTimer) return;
-  debounceTimer = setTimeout(flush, delayMs);
-}
-
-// Backoff for the undelivered-retry path. A pane parked at a shell, or a TUI
-// whose prompt never matches PROMPT_PATTERN, fails EVERY attempt — retrying on
-// the debounce window would spin capture-pane forever. Grows to a cap and
-// resets the moment a batch lands whole.
-let retryDelay = 0;
-function nextRetryDelay() {
-  retryDelay = retryDelay === 0 ? DEBOUNCE_MS : Math.min(retryDelay * 2, RETRY_MAX_MS);
-  return retryDelay;
-}
-
-// A pane can be permanently unpushable, and in the field that is the COMMON
-// failure — not the rare one. Measured over 11,507 receipts on one fleet: 1,004
-// pushes failed, and 1,001 of them were a single agent whose TUI never matched
-// PROMPT_PATTERN. Excluding it, the rest of the fleet failed 3 times in ~10,500.
-// The distribution is bimodal: near-zero where the pattern matches, TOTAL where
-// it does not. So "retry until it works" must not be the only behaviour — for a
-// blackout pane it would grow `pending` without bound and re-paste the whole
-// accumulation on every cycle.
-//
-// Instead: after GIVEUP_AFTER consecutive failed flushes, SUSPEND pushing and
-// rewind in-memory state to the on-disk cursor. Nothing is lost, because the
-// cursor was never advanced — the messages sit in the inbox file with the cursor
-// still pointing before them, so read_messages serves them and the agent gets
-// its traffic by polling. That is not a fallback invented here; it is what the
-// blackout agent above was already doing.
-const GIVEUP_AFTER = parseInt(process.env.AGENT_COORD_GIVEUP_AFTER || "5", 10);
-let consecutiveFailures = 0;
-let pushSuspended = false;
-let suspendedAt = 0;
-
-// Rewind to the on-disk cursor: forget what we staged, collected and queued.
-// stagedOffsets MUST be cleared — it is the only thing preventing re-collection,
-// and while suspended the on-disk cursor is the single source of truth for what
-// this agent has yet to see.
-function suspendPush(reason) {
-  pushSuspended = true;
-  suspendedAt = Date.now();
-  pending = [];
-  pendingCommits = [];
-  tierQueue.drain();
-  for (const k of Object.keys(stagedOffsets)) delete stagedOffsets[k];
-  process.stderr.write(
-    `[tmux-pusher] SUSPENDING push to '${TMUX_TARGET}' after ${consecutiveFailures} consecutive failures (${reason}). ` +
-      `The cursor was NOT advanced, so nothing is lost: this agent's traffic is still readable via read_messages. ` +
-      `Retrying in ${Math.round(RETRY_MAX_MS / 1000)}s. If this persists, the pane's TUI probably does not match ` +
-      `AGENT_COORD_PROMPT_PATTERN — fix that rather than waiting.\n`,
-  );
-}
-
-function resumePush() {
-  pushSuspended = false;
-  consecutiveFailures = 0;
-  retryDelay = 0;
-  process.stderr.write(`[tmux-pusher] resuming push attempts to '${TMUX_TARGET}'\n`);
-}
-
-async function flush() {
-  debounceTimer = null;
-  if (sending) {
-    scheduleFlush();
-    return;
-  }
-  if (pending.length === 0) return;
-  const batch = pending;
-  pending = [];
-  const commits = pendingCommits;
-  pendingCommits = [];
-  sending = true;
-  try {
-    // injectViaTmux reports what it could NOT put in the pane. Anything it
-    // hands back was never delivered, so its offsets must not be committed —
-    // the historical bug was committing the whole batch whenever inject
-    // returned without throwing, which silently dropped every message refused
-    // by the pane guard or left unsubmitted by pasteAndSubmit ({submitted:
-    // false} RESOLVES, it does not throw). Delivered messages are dropped from
-    // the retry set, so a partially-pasted batch neither loses its tail nor
-    // re-pastes its head.
-    const undelivered = await injectViaTmux(batch);
-    if (undelivered.length === 0) {
-      // Whole batch confirmed — only now advance the shared on-disk cursor
-      // past everything it (including its coalesced routine) covers. Dying
-      // before this line means redelivery on restart, never loss.
-      commitOffsets(commits);
-      retryDelay = 0;
-      consecutiveFailures = 0;
-      return;
-    }
-    // Partial or total refusal: hold the cursor where it is and retry only the
-    // part that never landed. Offsets stay pending, so a crash here rewinds to
-    // the last confirmed delivery rather than skipping the gap.
-    consecutiveFailures++;
-    process.stderr.write(
-      `[tmux-pusher] ${undelivered.length}/${batch.length} message(s) not delivered — cursor held, will retry\n`,
-    );
-    pending = [...undelivered, ...pending];
-    pendingCommits = [...commits, ...pendingCommits];
-    if (consecutiveFailures >= GIVEUP_AFTER) {
-      suspendPush("pane is not accepting pastes");
-      return;
-    }
-    scheduleFlush(nextRetryDelay());
-  } catch (e) {
-    process.stderr.write(`[tmux-pusher] inject failed: ${e?.message ?? e}\n`);
-    pending = [...batch, ...pending];
-    pendingCommits = [...commits, ...pendingCommits];
-    scheduleFlush(nextRetryDelay());
-  } finally {
-    sending = false;
-  }
-}
-
-// formatBatch lives in tier.mjs (pure, unit-tested): urgent verbatim under
-// the banner, then at most ONE coalesced digest block of queued routine.
-
-// Inject a batch, preserving order. Runs of ordinary peer messages go in as one
-// banner-wrapped paste; each control command (/clear, /compact) is injected on
-// its own as a RAW line so the TUI runs it as a slash command — a banner or
-// `[DM …]` prefix would turn it into plain chat text instead.
-// Returns the messages it could NOT deliver, in batch order — empty array when
-// the whole batch landed. NEVER returns normally on a refusal it has swallowed:
-// every path that declines to paste, or pastes without submitting, must surface
-// here, because the caller commits the shared cursor on an empty return.
-async function injectViaTmux(batch) {
-  // Fail-closed pane guard: never type into a pane that has dropped to a shell
-  // (crashed/exited agent CLI). Bracketed paste protects a compliant TUI, but a
-  // raw shell would execute pasted lines — so refuse, and report the whole
-  // batch undelivered so the cursor stays put and it redelivers once the agent
-  // CLI is back. (Reporting nothing here is what made "will redeliver" a lie.)
-  const cmd = paneCurrentCommand();
-  if (cmd !== null && SHELL_COMMANDS.has(cmd)) {
-    process.stderr.write(
-      `[tmux-pusher] pane '${TMUX_TARGET}' is at a shell ('${cmd}'), not the agent CLI — skipping inject (will redeliver)\n`,
-    );
-    return [...batch];
-  }
-  // Phase 5.3 Task 21.2 — STAMP THE REPLAY FACT BEFORE PASTING.
-  //
-  // Read once per inject, not per message: the receipt log is append-only and a
-  // single read is a consistent snapshot for the whole batch.
-  //
-  // WHY THIS FILE IS THE RIGHT PLACE, and why it can work at all: receipts are
-  // stamped AFTER a payload is typed (writeReceipts, below) and the push cursor
-  // advances only after the whole batch lands (commitOffsets, in flush). So a
-  // death anywhere in that window redelivers a message whose receipt is ALREADY
-  // on disk — the evidence exists before the duplicate can, without anyone
-  // having recorded anything for this purpose or remembered anything at all.
-  //
-  // Best-effort: an unreadable receipt log yields an empty map and therefore no
-  // markers, which is the honest direction. A missing marker means "no earlier
-  // delivery is RECORDED", never "this is provably the first" — see replay.mjs.
-  let prior = new Map();
-  try {
-    prior = priorDeliveries(readFileSync(RECEIPTS_FILE, "utf8"));
-  } catch {
-    // no receipts yet, or unreadable — every message renders as a first delivery
-  }
-  batch = batch.map((m) => {
-    const replay = replayInfo(prior, m?.id);
-    return replay ? { ...m, replay } : m;
-  });
-
-  const undelivered = [];
-  let run = [];
-  const flushRun = async () => {
-    if (run.length === 0) return;
-    const inRun = run;
-    run = [];
-    let outcome;
-    try {
-      // bracketed=true → submit.mjs verifies by default (paste-chip land + Enter retry).
-      outcome = await pasteAndSubmit(formatBatch(inRun, AGENT_ID, joinedRooms()), true);
-    } catch (e) {
-      // A throw here (nonzero paste-buffer/send-keys) must not abort the whole
-      // batch: runs already pasted ARE delivered, and propagating would make
-      // the caller re-queue them and paste the head twice — the duplicate-DM
-      // symptom. Fail just this run.
-      process.stderr.write(`[tmux-pusher] peer paste failed: ${e?.message ?? e}\n`);
-      undelivered.push(...inRun);
-      return;
-    }
-    if (outcome && outcome.submitted === false) {
-      // pasteAndSubmit RESOLVES {submitted:false} for: paste never seen in the
-      // input within PASTE_VERIFY_MS, input line unreadable / no PROMPT_PATTERN
-      // match, or still-in-input after ENTER_RETRIES. All three are delivery
-      // failures, not warnings.
-      process.stderr.write(`[tmux-pusher] peer paste NOT submitted: ${outcome.reason}\n`);
-      undelivered.push(...inRun);
-    }
-    writeReceipts(inRun, outcome); // stamp only AFTER the paste+submit resolves
-  };
-  for (const m of batch) {
-    if (isControl(m)) {
-      await flushRun();
-      // Control commands are VERIFIED: capture-pane confirms the command
-      // actually left the input. A receipt that says "typed" was being read
-      // as "ran" — see writeReceipts.
-      let outcome;
-      try {
-        outcome = await submitControlCommand(m.text.trim());
-      } catch (e) {
-        process.stderr.write(`[tmux-pusher] control command failed: ${e?.message ?? e}\n`);
-        undelivered.push(m);
-        continue;
-      }
-      if (outcome && outcome.submitted === false) undelivered.push(m);
-      writeReceipts([m], outcome);
-    } else {
-      run.push(m);
-    }
-  }
-  await flushRun();
-  return undelivered;
-}
-
-// Append one delivery receipt per message AFTER it has been typed into the
-// pane. Receipts are out-of-band proof for the sender (it polls this file),
-// never injected into any agent's context — so verification costs zero tokens.
-// Best-effort: a failed receipt write must not break delivery, so we swallow.
-// `outcome` (control commands only) carries what verification actually saw.
-// WITHOUT it a receipt proved the pusher TYPED the command, and send_command
-// reported that as delivery:"confirmed" — proof of typing sold as proof of
-// execution. `submitted` is the honest field: false means it is still sitting
-// in the input, and the sender is told so instead of being reassured.
-function writeReceipts(msgs, outcome) {
-  const lines = [];
-  for (const m of msgs) {
-    if (!m || !m.id) continue;
-    lines.push(
-      JSON.stringify({
-        id: m.id,
-        agentId: AGENT_ID,
-        ts: Date.now(),
-        from: m.from,
-        control: m.control === true,
-        // Build identity of the pusher that did the typing/verifying — the
-        // same module-graph stamp the transport marker carries (SCRIPT_MTIME
-        // covers hooks/*.mjs, not just this file). Lets deliveryOutcome note
-        // a "confirmed" issued by pre-upgrade verification logic. Omitted
-        // when unknown: absence reads as UNKNOWN downstream, never as fresh.
-        ...(SCRIPT_MTIME !== undefined ? { scriptMtime: SCRIPT_MTIME } : {}),
-        ...(outcome
-          ? {
-              submitted: outcome.submitted === true,
-              verified: outcome.verified === true,
-              ...(outcome.reason ? { reason: outcome.reason } : {}),
-            }
-          : {}),
-      }),
-    );
-  }
-  if (lines.length === 0) return;
-  try {
-    appendFileSync(RECEIPTS_FILE, lines.join("\n") + "\n");
-  } catch (e) {
-    process.stderr.write(`[tmux-pusher] receipt write failed: ${e?.message ?? e}\n`);
-  }
-}
-
-// bracketed=true wraps the paste in bracketed-paste markers (paste-buffer -p) so
-// a compliant TUI treats the payload as inert data — embedded newlines can't
-// submit lines or smuggle a "/command". Control commands (/clear, /compact) must
-// paste RAW (bracketed=false) so the TUI still runs them as slash commands.
-//
-// The pipeline itself lives in ./submit.mjs, shared with scripts/coord-pusher.mjs
-// so the two cannot drift again. This wrapper only supplies tmux.
-const tmuxDeps = {
-  target: TMUX_TARGET,
-  buffer: BUFFER_NAME,
-  run: (args) => spawnSync("tmux", args, { encoding: "utf8" }),
-  runStdin: (args, payload) =>
-    new Promise((resolve, reject) => {
-      const load = spawn("tmux", args);
-      load.on("error", reject);
-      load.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`tmux ${args[0]} exit ${code}`))));
-      load.stdin.end(payload);
-    }),
-};
-
-function pasteAndSubmit(payload, bracketed = false) {
-  return sharedPasteAndSubmit(tmuxDeps, payload, { bracketed });
-}
-
-// Control commands go through the preflight + verify path, never the plain one.
-function submitControlCommand(payload) {
-  return sharedSubmitControl(tmuxDeps, payload);
-}
-
-// Publish transport marker so list_agents can show this agent is push-capable.
-writeTransportMarker();
-{
-  const guardLine = readyProfileStartupLine("tmux-pusher");
-  if (guardLine) process.stderr.write(guardLine);
-}
-let markerCleaned = false;
-const cleanupMarker = () => {
-  if (markerCleaned) return;
-  markerCleaned = true;
-  try {
-    unlinkSync(TRANSPORT_FILE);
-  } catch {
-    // already gone
-  }
-};
-// Log BEFORE cleaning up. A silent exit that also removes its own marker is
-// indistinguishable from "never attached" — on 2026-07-28 all four pushers on
-// the bus vanished at once and the cause could not be determined afterwards,
-// because every other exit path logs and this one did not. Ruled out at the
-// time: dead-pane self-exit (logs), die() (logs), SIGKILL/OOM (the marker
-// would have survived), a normal exit (the poll intervals are not unref'd),
-// doctor's reaper (has-session returned 0 for every live pane), tests (all
-// isolate AGENT_COORD_DIR), coord-chat (not running), stop-agent.sh (would
-// have killed the session too) and a parent process-group signal (the pusher
-// has its own PGID and SID). That left a signal from outside the repo, with
-// nothing recorded to identify it.
-function logSignal(sig) {
-  process.stderr.write(
-    `[tmux-pusher] received ${sig} — cleaning up marker for '${AGENT_ID}' (pane ${TMUX_TARGET}, pid ${process.pid}) and exiting\n`,
-  );
-}
-
-process.on("SIGINT", () => {
-  logSignal("SIGINT");
-  cleanupMarker();
-  process.exit(0);
-});
-process.on("SIGTERM", () => {
-  logSignal("SIGTERM");
-  cleanupMarker();
-  process.exit(0);
-});
-process.on("exit", cleanupMarker);
-
-function writeTransportMarker() {
-  // Merge over the existing marker, never rebuild from scratch: attach_agent
-  // wrote it first and owns fields only the server can know (its
-  // serverBuildMtime provenance stamp, and whatever comes next). A
-  // from-scratch rewrite here once dropped scriptMtime and silently disabled
-  // doctor's stale-pusher-script check — see hooks/marker.mjs.
-  let existing;
-  try {
-    existing = JSON.parse(readFileSync(TRANSPORT_FILE, "utf8"));
-  } catch {
-    existing = undefined; // first writer, or unreadable — our own fields stand alone
-  }
-  const marker = mergeTransportMarker(existing, {
-    agentId: AGENT_ID,
-    transport: "tmux-push",
-    pid: process.pid,
-    tmuxTarget: TMUX_TARGET,
-    since: Date.now(),
-    // MUST be included: attach_agent stamps this too, but this write happens
-    // afterwards and would otherwise clobber it — and doctor SKIPS markers
-    // without it (pre-v0.8.2 shape), so dropping it silently disabled the
-    // stale-pusher-script check for every local pusher. Our own stamp is the
-    // more truthful value anyway: it reflects the code THIS process loaded.
-    scriptMtime: SCRIPT_MTIME,
-  });
-  const tmp = TRANSPORT_FILE + ".tmp";
-  writeFileSync(tmp, JSON.stringify(marker));
-  renameSync(tmp, TRANSPORT_FILE);
-}
-
-// Initial drain in case messages accumulated before the daemon started.
-checkOnce();
-
-// Watch + poll fallback.
-try {
-  if (existsSync(INBOX_FILE)) watch(INBOX_FILE, () => checkOnce());
-} catch {
-  // file may not exist yet; polling covers it
-}
-if (INCLUDE_ROOM) {
-  for (const chan of joinedRooms()) watchRoom(chan);
-}
-setInterval(checkOnce, POLL_MS);
-// Self-exit when our target pane disappears (agent closed its window or crashed
-// without unregister). Without this the daemon lingers with a live pid, so its
-// transport marker reads as "live" forever and list_agents keeps the ghost
-// agent online. cleanupMarker (also wired to process exit) drops the marker.
-setInterval(checkTargetAlive, POLL_MS);
-
-process.stderr.write(
-  `[tmux-pusher] watching inbox for '${AGENT_ID}' -> tmux ${TMUX_TARGET} (room=${INCLUDE_ROOM ? "on" : "off"})\n`,
-);
-
-// Probe the target pane; after TARGET_GRACE consecutive misses, give up and
-// exit cleanly so the marker is removed and the agent stops looking attached.
-function checkTargetAlive() {
-  // `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
-  // DOES NOT — tmux exits 0 for any target, including a pane killed a moment
-  // ago, so the probe had ZERO discriminating power and reported every dead
-  // pane alive. Pinned to the BEHAVIOUR, not a version: measured identical on
-  // tmux 3.6b and 3.7b, and a version-pinned claim rots on the next upgrade.
-  // Positive control, both directions: bogus target -> has-session exit 1,
-  // display-message exit 0; live pane -> both exit 0.
-  const p = spawnSync("tmux", ["has-session", "-t", TMUX_TARGET]);
-  if (p.status === 0) {
-    targetMisses = 0;
-    return;
-  }
-  targetMisses++;
-  if (targetMisses >= TARGET_GRACE) {
-    process.stderr.write(
-      `[tmux-pusher] target '${TMUX_TARGET}' gone for ${targetMisses} probe(s) — cleaning up and exiting\n`,
-    );
-    cleanupMarker();
-    process.exit(0);
-  }
-}
-
-function die(msg) {
-  process.stderr.write(`[tmux-pusher] ${msg}\n`);
-  process.exit(1);
-}
-
-// ---------- channel helpers (mirror src/store.ts) ----------
-
-function normalizeRoom(name) {
-  if (!name) return DEFAULT_ROOM;
-  const n = String(name).trim().replace(/^#+/, "").toLowerCase().replace(/[^a-z0-9._-]/g, "");
-  return n || DEFAULT_ROOM;
-}
-
-function roomFile(chan) {
-  const c = normalizeRoom(chan);
-  // c is already normalized to a filesystem-safe charset.
-  return c === DEFAULT_ROOM ? path.join(ROOT, "room.jsonl") : path.join(ROOT, "rooms", `${c}.jsonl`);
-}
-
-function getRoomOffset(cursor, chan) {
-  const c = normalizeRoom(chan);
-  return c === DEFAULT_ROOM ? cursor.roomOffset ?? 0 : cursor.roomOffsets?.[c] ?? 0;
-}
-
-function setRoomOffset(cursor, chan, n) {
-  const c = normalizeRoom(chan);
-  if (c === DEFAULT_ROOM) cursor.roomOffset = n;
-  else (cursor.roomOffsets ??= {})[c] = n;
-}
-
-// Channels this agent is a MEMBER of, per rooms.json. #general included only
-// if membership says so.
-//
-// It used to be seeded `new Set([DEFAULT_ROOM])` before the membership loop, so
-// every pusher tailed #general whether or not the agent had ever joined it —
-// membership was honoured for every channel except the one with the most
-// traffic. Observed directly: rooms.json read `general -> 0 members []` while
-// agents joined only to a project room were taking #general cross-project
-// broadcasts into their panes.
-//
-// Deliberate consequence of dropping the seed: no registry (or an unparseable
-// one) now yields NO channels rather than #general. Absence of a registry is
-// absence of evidence of membership, and the safe reading of "I cannot tell
-// whether this agent joined" is not "push to it" — that is the assumption that
-// produced the defect. Nothing is lost either way: offsets are untouched here,
-// so read_messages still serves whatever the pusher did not.
-//
-// Cursor safety: this function only decides what gets TAILED. Offsets advance
-// exclusively in collectRoomChannel, which runs only for the channels returned
-// here — so a channel this agent is not in has its offset left exactly where it
-// was, and joining later resumes from that point. Not stranded (read_messages
-// reads the same cursor), not skipped (nothing advanced it meanwhile), not
-// double-served (the offset is preserved, not reset).
-function joinedRooms() {
-  let reg = {};
-  try {
-    const raw = readFileSync(path.join(ROOT, "rooms.json"), "utf8");
-    if (raw.trim()) reg = JSON.parse(raw);
-  } catch {
-    // no registry yet → no memberships to honour
-  }
-  const out = new Set();
-  for (const [chan, e] of Object.entries(reg)) {
-    if (e && Array.isArray(e.members) && e.members.includes(AGENT_ID)) out.add(chan);
-  }
-  return [...out];
-}
-
-function watchRoom(chan) {
-  const f = roomFile(chan);
-  if (watchedRooms.has(f)) return;
-  try {
-    if (existsSync(f)) {
-      watch(f, () => checkOnce());
-      watchedRooms.add(f);
-    }
-  } catch {
-    // polling covers it until the file exists
-  }
-}