agent-coord-mcp 0.26.24 → 0.26.25

package/src/server-spread.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
 /*
  * ⛔⛆⛆ TWO SEATS RAN THE SAME VERB, GOT `153` AND `138`, AND BOTH SERVERS HONESTLY
  * REPORTED `versionLabel 0.26.20` — `⟨q-cec42e20⟩`.
@@ -95,9 +97,19 @@ const sideOf = (startedAt: number, installMtime: number): Cohort["side"] =>
  * read agrees. The cohorts are still returned, so a reader sees what was established as
  * well as what was not.
  */
+/** Is a stamped server pid still running? EPERM means it exists and is not ours. */
+export function pidRunning(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return (e as NodeJS.ErrnoException).code === "EPERM"; }
+}
+
 export function detectSpread(
   identities: ServerIdentity[],
   installed: InstalledBuild | null,
+  // PURE BY DEFAULT: the detector trusts a stamped pid unless the caller supplies a liveness
+  // check. The production caller (`list_agents`) passes `pidRunning`; a fixture of a measured
+  // incident, whose pids belong to processes long gone, is still placed by its stamps.
+  { isRunning = () => true }: { isRunning?: (pid: number) => boolean } = {},
 ): SpreadVerdict {
   const uncomparable: Uncomparable[] = [];
   const placed: { agentId: string; side: Cohort["side"]; module?: string }[] = [];
@@ -120,6 +132,16 @@ export function detectSpread(
       });
       continue;
     }
+    // ⟨q-18a719c5⟩ A STAMP OUTLIVES ITS SERVER. If the process that stamped this entry is gone,
+    // the module it names is what a DEAD process ran — not what serves the seat now. Unknown,
+    // naming the pid, until the seat's next server binds and stamps over it.
+    if (typeof id.serverPid === "number" && !isRunning(id.serverPid)) {
+      uncomparable.push({
+        agentId: id.agentId,
+        why: `stamped by server pid ${id.serverPid}, which is no longer running — the entry names a process that is gone, not the one serving this seat`,
+      });
+      continue;
+    }
     if (installed === null) continue;
     // ⭐ A DIFFERENT BUILD IS ITS OWN COHORT, never folded into `pre-install`: "which
     // side of the install did you start" is not a question about a process that does
@@ -156,6 +178,12 @@ export function detectSpread(
       uncomparable,
     };
   }
+  // ⟨q-18a719c5⟩ UNKNOWNS BLOCK AGREEMENT, NOT DISAGREEMENT. Two readable seats on different
+  // sides of the install is established whatever the unreadable ones run, so it is reported as
+  // DIVERGED with the unknowns listed. Only AGREED needs every seat, and that rule (#293) stands.
+  if (uncomparable.length && cohorts.length > 1) {
+    return { state: "DIVERGED", cohorts, comparable, uncomparable };
+  }
   if (uncomparable.length) {
     return {
       state: "CANNOT_COMPARE",
@@ -218,15 +246,35 @@ export function reportSpread(v: SpreadVerdict, installed: InstalledBuild | null)
  * question is "what build is the answering process running", and the answering process
  * is the one executing this file.
  */
+export const COORD_MCP_PACKAGE_NAME = "agent-coord-mcp";
+
 export function installedBuild(
   fromUrl: string,
   statSync: (p: string) => { mtimeMs: number },
+  readFile: (p: string) => string = (p) => readFileSync(p, "utf8"),
 ): InstalledBuild | null {
+  // ⟨q-18a719c5⟩ THE ROOT IS FOUND BY THE PACKAGE'S OWN IDENTITY, not by a depth. This used to
+  // strip one level (`/dist/<file>`), and both production callers live in
+  // `dist/tools/registry.js`: the regex never matched, `statSync(".../registry.js/package.json")`
+  // threw, and this returned null on every server — `serverSpread` read CANNOT_COMPARE on every
+  // fleet and the heartbeat stamp wrote `serverModule: undefined`. A depth count, or the FIRST
+  // package.json found, breaks in other layouts (a global npm or homebrew install nests the
+  // package under node_modules, a workspace nests it under packages/); the package.json whose
+  // `name` is agent-coord-mcp is the package in every one of them. Nothing found stays null.
   try {
-    // dist/server-spread.js -> the package root two levels up
-    const here = new URL(fromUrl).pathname;
-    const root = here.replace(/\/dist\/[^/]*$/, "");
-    return { mtime: statSync(`${root}/package.json`).mtimeMs, module: root };
+    let dir = path.dirname(decodeURIComponent(new URL(fromUrl).pathname));
+    for (let hops = 0; hops < 12; hops++) {
+      const pkg = path.join(dir, "package.json");
+      try {
+        if (JSON.parse(readFile(pkg))?.name === COORD_MCP_PACKAGE_NAME) {
+          return { mtime: statSync(pkg).mtimeMs, module: dir };
+        }
+      } catch { /* no readable package.json here — keep walking */ }
+      const up = path.dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+    return null;
   } catch {
     return null;
   }

package/src/server.ts

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { readyProfileStartupLine } from "../hooks/submit.mjs";
 import { randomUUID } from "node:crypto";
-import { initTransportFromConfig } from "./transports/index.js";
+import { HERDR, initTransportFromConfig } from "./transports/index.js";
+import { startTailOnBind, stopHerdrTail } from "./tools/herdr-tail.js";
 import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -37,6 +40,7 @@ import {
   forceUnregisterTool,
   heartbeatSchema,
   heartbeatTool,
+  stampServerIdentity,
   joinRoomSchema,
   joinRoomTool,
   joinSchema,
@@ -334,6 +338,12 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
               const via = await guardFirstClaim(claimed, args);
               bound = claimed;
               recordSessionBinding(claimed, via);
+              // ⛔ THE TAIL STARTS HERE, AT THE BINDING — not from an env var no seat sets.
+              startTailOnBind(claimed);
+              // ⟨q-18a719c5⟩ A server that re-binds WITHOUT `join` (a restart that first calls
+              // attach_agent, or any gated tool) serves the seat from now on: stamp the entry if it
+              // exists. A seat not yet registered is stamped by the `register` that creates it.
+              await stampServerIdentity(claimed);
             }
           } else if (bound !== claimed) {
             throw new Error(
@@ -384,6 +394,8 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           const via = await guardFirstClaim(claimed, args);
           bound = claimed;
           recordSessionBinding(claimed, via);
+          // ⛔ THE TAIL STARTS HERE, AT THE BINDING — not from an env var no seat sets.
+          startTailOnBind(claimed);
         } else if (bound !== claimed) {
           throw new Error(
             `identity bound to '${bound}'; rejected attempt to act as '${claimed}'`,
@@ -550,6 +562,8 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           const via = await guardFirstClaim(claimed, args);
           bound = claimed;
           recordSessionBinding(claimed, via);
+          // ⛔ THE TAIL STARTS HERE, AT THE BINDING — not from an env var no seat sets.
+          startTailOnBind(claimed);
         } else if (bound !== claimed) {
           throw new Error(`identity bound to '${bound}'; rejected attempt to act as '${claimed}'`);
         }
@@ -558,8 +572,14 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
       if (result && typeof result === "object" && (result as { ok?: unknown }).ok === true) {
         const to = (result as { to?: unknown }).to;
         if (typeof to === "string") {
+          const from = bound;
           bound = to;
           recordSessionBinding(to, "rename");
+          // ⛔ THE TAIL MOVES WITH THE IDENTITY. The coordinator's gate measured a renamed herdr seat
+          // still tailing its OLD id's inbox — `herdrTail` listed only the old name — so the seat
+          // went deaf under its new one. Stop the old, start the new.
+          if (from && from !== to) stopHerdrTail(from);
+          startTailOnBind(to);
         }
       }
       return jsonResult(result);
@@ -828,6 +848,23 @@ async function main() {
     if (t.source !== "default") {
       console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
     }
+    // ⛔ A HERDR SEAT MUST TAIL ITS OWN INBOX, OR IT IS DEAF TO EVERY TMUX SENDER.
+    // The send-time path can only see the SENDER's transport (a module-level singleton), so a
+    // tmux seat's server can never type into a herdr pane. The duty belongs to the seat that
+    // needs waking — the only party guaranteed to be where it is — and this is where it starts.
+    // The env var is ONE way to bind identity, and no seat on this fleet uses it — they bind at
+    // `join`. So this branch only covers a server launched pre-bound; the tail's real start is the
+    // binding hook below, which runs at every bind. A herdr server with neither simply waits.
+    // ⟨q-15d763dc⟩ A herdr server types into panes itself, so an unguarded one says so at start.
+    if (t.kind === HERDR) {
+      const guardLine = readyProfileStartupLine("agent-coord-mcp");
+      if (guardLine) console.error(guardLine.trimEnd());
+    }
+    if (t.kind === HERDR && process.env.AGENT_COORD_BOUND_AGENT) {
+      startTailOnBind(process.env.AGENT_COORD_BOUND_AGENT);
+    } else if (t.kind === HERDR) {
+      console.error("[agent-coord-mcp] herdr transport: the inbox tail starts when this session binds its identity (join)");
+    }
   } catch (e) {
     // Loud, and fatal. A server that starts with an unusable transport config
     // delivers nothing while reporting itself up, and a quiet transport is the

package/src/tools/herdr-delivery.ts

@@ -20,13 +20,15 @@
  * `[agent-coord] …` banner and the attributed line) but one at a time. Tiers still decide
  * the banner text. Batching for herdr is Task 5 territory if it is wanted.
  */
-import { statSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { activeTransport, HERDR, type TransportMarker } from "../transports/index.js";
 import { ROOT, inboxFile, roomFile } from "../store.js";
 import { loadLiveTransports } from "./registry.js";
+import { newMessagesIn } from "./jsonl-offsets.js";
 import type { Message } from "./shared.js";
+export type { Message };
 
 type Tier = { formatBatch: (batch: unknown[], agentId: string, rooms: string[]) => string; classifyTier: (m: unknown, opts?: unknown) => string };
 type PushCursor = { readPushCursor: (root: string, safeId: string) => Record<string, unknown>; writePushCursor: (root: string, safeId: string, c: Record<string, unknown>) => void };
@@ -42,7 +44,64 @@ function loadHooks(): Promise<{ tier: Tier; cursor: PushCursor }> {
 }
 const safeId = (id: string) => id.replace(/[^A-Za-z0-9._-]/g, "_");
 
-export type HerdrDeliveryOutcome = { agentId: string; delivered: boolean; enters?: number; error?: string; cursorAdvanced: boolean };
+
+export type Where = { kind: "dm" } | { kind: "room"; chan: string };
+
+/**
+ * ⭐ ONE RENDERER AND ONE CURSOR RULE, SHARED BY BOTH PATHS. The send-time path
+ * (`deliverToHerdrSeats`) and the seat's own tail (`herdr-tail.ts`) must produce the same bytes
+ * in the pane and must move the same cursor the same way — a second copy of either is a second
+ * truth about what a seat has already seen, and the copy is the one that rots.
+ */
+export async function renderForPane(msg: Message, agentId: string, where: Where): Promise<string> {
+  const { tier } = await loadHooks();
+  const tagged = { ...msg, tag: where.kind === "dm" ? "DM" : `room #${where.chan}` };
+  return tier.formatBatch([{ ...tagged, tier: tier.classifyTier(tagged) }], agentId, where.kind === "room" ? [where.chan] : []);
+}
+
+/**
+ * Advance the PUSH cursor past everything currently in the source. Returns whether it moved.
+ * ⛔ Called ONLY after a verified delivery — that is the rule this whole module exists to keep.
+ */
+export async function advancePushCursor(agentId: string, where: Where, toOffset?: number): Promise<boolean> {
+  try {
+    const { cursor } = await loadHooks();
+    // ⛔ THE CURSOR DIRECTORY MUST EXIST OR THE WRITE FAILS SILENTLY, AND A CURSOR THAT NEVER
+    // ADVANCES RE-TYPES THE SAME MESSAGE ON EVERY TICK — a paste loop into a live pane. Found by
+    // the tail's own double-delivery test against a fresh bus directory, where `cursors/` had not
+    // been created yet: `writePushCursor` threw ENOENT, the `catch` below turned it into
+    // `false`, and the delivery looked fine from every other angle.
+    mkdirSync(path.join(ROOT, "cursors"), { recursive: true });
+    const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
+    // `toOffset` is the byte just past the line that was delivered. Without it (the send-time path,
+    // where the just-appended message IS the last line) the file size is the same number.
+    const size = toOffset ?? statSync(file).size;
+    const id = safeId(agentId);
+    const c = cursor.readPushCursor(ROOT, id) ?? {};
+    if (where.kind === "dm") c.inboxOffset = Math.max(Number(c.inboxOffset ?? 0), size);
+    else {
+      const offsets = ((c.roomOffsets as Record<string, number> | undefined) ?? {});
+      offsets[where.chan] = Math.max(Number(offsets[where.chan] ?? 0), size);
+      c.roomOffsets = offsets;
+    }
+    cursor.writePushCursor(ROOT, id, c);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The push cursor as the pusher stores it, for a caller that needs to read an offset. */
+export async function readPushCursorFor(agentId: string): Promise<Record<string, unknown>> {
+  try {
+    const { cursor } = await loadHooks();
+    return cursor.readPushCursor(ROOT, safeId(agentId)) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export type HerdrDeliveryOutcome = { agentId: string; delivered: boolean; enters?: number; error?: string; cursorAdvanced: boolean; deferred?: string };
 
 /** Deliver one just-appended message to every herdr-attached recipient among `recipients`. */
 export async function deliverToHerdrSeats(msg: Message, recipients: string[], where: { kind: "dm" } | { kind: "room"; chan: string }): Promise<HerdrDeliveryOutcome[]> {
@@ -56,32 +115,41 @@ export async function deliverToHerdrSeats(msg: Message, recipients: string[], wh
     if (!marker || marker.transport !== HERDR) continue;
     if (where.kind === "room" && marker.rooms === false) continue;
     if (msg.from === agentId) continue;
-    const { tier, cursor } = await loadHooks();
-    const tagged = { ...msg, tag: where.kind === "dm" ? "DM" : `room #${where.chan}` };
-    const rendered = tier.formatBatch([{ ...tagged, tier: tier.classifyTier(tagged) }], agentId, where.kind === "room" ? [where.chan] : []);
+    // ⛔ ORDER BEFORE SPEED. This path runs in the SENDER's server at send time. If an EARLIER
+    // message to this seat is still owed — a paste that failed, which the seat's own tail is
+    // retrying — typing this one now and moving the cursor would jump past the owed one, and the
+    // tail's retry would find the cursor already beyond it: that message would never be typed.
+    // The coordinator's gate named the old call as "still advances the cursor to EOF"; measured,
+    // it did exactly that. So: find THIS message after the persisted cursor; if any earlier
+    // message to someone else precedes it, defer to the recipient's tail, which delivers in order.
+    const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
+    const c = await readPushCursorFor(agentId);
+    const from = where.kind === "dm" ? Number(c.inboxOffset ?? 0) : Number(((c.roomOffsets as Record<string, number> | undefined) ?? {})[where.chan] ?? 0);
+    const after = newMessagesIn(file, from);
+    const at = after.findIndex((m) => m.msg.id === msg.id);
+    const owed = at === -1 ? [] : after.slice(0, at).filter((m) => m.msg.from !== agentId);
+    if (at === -1 || owed.length > 0) {
+      out.push({
+        agentId,
+        delivered: false,
+        cursorAdvanced: false,
+        deferred: at === -1
+          ? "this message is not after the push cursor (already delivered, or the file moved) — left to the recipient's tail"
+          : `${owed.length} earlier message(s) to this seat are still owed — left to the recipient's own tail, which delivers in order`,
+      });
+      continue;
+    }
+    const rendered = await renderForPane(msg, agentId, where);
     // A control never comes through here: send_command hands a herdr seat's control to the
     // transport's sendControl directly (a raw-vs-rendered branch here was dead and its
     // mutation survived, so it is gone). Everything delivered here is a rendered message.
-    let r: { delivered: boolean; error?: string; enters?: number };
+    let r: { delivered: boolean; error?: string; enters?: number; verified?: boolean };
     try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, error: (e as Error).message }; }
-    let cursorAdvanced = false;
-    if (r.delivered) {
-      try {
-        const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
-        const size = statSync(file).size;
-        const id = safeId(agentId);
-        const c = cursor.readPushCursor(ROOT, id) ?? {};
-        if (where.kind === "dm") c.inboxOffset = Math.max(Number(c.inboxOffset ?? 0), size);
-        else {
-          const offsets = ((c.roomOffsets as Record<string, number> | undefined) ?? {});
-          offsets[where.chan] = Math.max(Number(offsets[where.chan] ?? 0), size);
-          c.roomOffsets = offsets;
-        }
-        cursor.writePushCursor(ROOT, id, c);
-        cursorAdvanced = true;
-      } catch { cursorAdvanced = false; }
-    }
-    out.push({ agentId, delivered: r.delivered, enters: r.enters, error: r.error, cursorAdvanced });
+    // ⟨q-15d763dc⟩ Only a VERIFIED delivery moves the cursor; anything less leaves the message owed.
+    const verified = r.delivered && r.verified === true;
+    // Exactly past THIS message's line — never to the end of the file, which may already hold a later one.
+    const cursorAdvanced = verified ? await advancePushCursor(agentId, where, after[at]!.end) : false;
+    out.push({ agentId, delivered: verified, enters: r.enters, error: r.error ?? (r.delivered ? "delivered but not verified — cursor held (q-15d763dc)" : undefined), cursorAdvanced });
   }
   return out;
 }

package/src/tools/herdr-tail.ts

@@ -0,0 +1,244 @@
+/**
+ * ⛔ A HERDR SEAT WAS DEAF TO EVERY TMUX SEAT, AND THE REASON IS A SINGLETON.
+ *
+ * `deliverToHerdrSeats` runs at SEND time and returns early unless `activeTransport().kind` is
+ * HERDR. `activeTransport()` returns a module-level singleton wired once at startup from the
+ * SENDER's own config — so that early return can only ever see the SENDER's transport, and a tmux
+ * seat's server could never type into a herdr pane. Measured both ways: `herdr → herdr` typed and
+ * woke the seat; `tmux → herdr` reached the inbox file and was never typed.
+ *
+ * ⚠ THE EASIER FIX IS THE WRONG ONE: letting the SENDER drive herdr per recipient passes on a
+ * one-machine fleet and fails silently and asymmetrically on two, because every sender would need
+ * the `herdr` binary on its own host. So the duty goes to the seat that needs waking — the only
+ * party guaranteed to be where it is.
+ *
+ * ⛔⛆ AND THE FIRST VERSION OF THIS FILE WAS INERT ON EVERY SEAT, INCLUDING ITS AUTHOR'S.
+ * `8363968` started the tail only when `AGENT_COORD_BOUND_AGENT` was set at startup. No seat on
+ * this fleet sets it — identity binds at `join` — so the coordinator measured "herdr tail NOT
+ * started" on the PR's own server and qa read the variable unset on all six live seat servers.
+ * Its eleven tests injected the agent id and so could not see it. The tail now starts from the
+ * IDENTITY BINDING (`startTailOnBind`), idempotently, one per agent per process.
+ *
+ * ⛔ AND IT MUST NOT RUN THE REAPER. That version called `loadLiveTransports()` on every tick —
+ * the loader that DELETES markers it judges dead, named an hour earlier as the vanishing-marker
+ * mechanism. A reaper in a once-a-second loop on every seat is not shippable on the argument that
+ * the current build usually keeps the marker. This file reads its own seat's marker FILE directly,
+ * read-only, and never asks about anyone else's.
+ *
+ * THE CURSOR RULE IS THE PUSHER'S (⟨q-7be94b5e⟩): advance the PUSH cursor only past what was
+ * VERIFIABLY typed. Two corrections from qa's read of `8363968`, both now driven by tests:
+ *   · the cursor advances to the byte AFTER THE DELIVERED LINE, never to the file's size — sizing
+ *     it skipped a later message in the same tick whose paste then failed;
+ *   · a cursor write that FAILS is held, and an in-process high-water mark stops the same message
+ *     being re-typed on the next tick — the directory fix closed one cause of a paste loop, this
+ *     closes the class.
+ *
+ * IDLE COST, COUNTED BY TESTS RATHER THAN ASSERTED HERE: when no tailed file has grown, a tick is
+ * one `stat()` per tailed file and nothing else. The marker and room membership are re-read every
+ * `REFRESH_TICKS` ticks, and no herdr subprocess runs until there is something to type.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { inboxFile, roomFile, getRooms, transportFile } from "../store.js";
+import { activeTransport, HERDR, type Transport, type TransportMarker } from "../transports/index.js";
+import { renderForPane, advancePushCursor, readPushCursorFor, type Message } from "./herdr-delivery.js";
+import { newMessagesIn } from "./jsonl-offsets.js";
+
+export const DEFAULT_POLL_MS = 1000;
+/** Marker and room membership are re-read this often. A room joined mid-session is picked up within this many ticks. */
+export const REFRESH_TICKS = 30;
+
+type Source = { kind: "dm" | "room"; chan?: string; file: string };
+export type TailOutcome = {
+  delivered: { kind: "dm" | "room"; chan?: string; id: string }[];
+  held: { kind: "dm" | "room"; chan?: string; id: string; why: string }[];
+  idle?: string;
+};
+
+/** Per-agent memory that survives between ticks — what makes the idle path cheap and the paste loop impossible. */
+export type TailContext = {
+  tick: number;
+  marker: TransportMarker | null;
+  rooms: string[];
+  /** In-process high-water mark per source: never re-type below this, even if the persistent cursor could not be written. */
+  hw: Map<string, number>;
+  /** Last seen size per source: a source that has not grown costs one stat. */
+  sizes: Map<string, number>;
+};
+export const newContext = (): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map() });
+
+const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
+const sizeOf = (file: string): number => {
+  try { return statSync(file).size; } catch { return 0; }
+};
+
+/** Read THIS seat's own marker, read-only. Never the reaping loader. */
+export function readOwnMarker(agentId: string): TransportMarker | null {
+  try { return JSON.parse(readFileSync(transportFile(agentId), "utf8")) as TransportMarker; } catch { return null; }
+}
+
+/** The shared line reader — re-exported so callers of this module keep one import. */
+export { newMessagesIn } from "./jsonl-offsets.js";
+
+async function offsetOf(agentId: string, src: Source, ctx: TailContext): Promise<number> {
+  const c = await readPushCursorFor(agentId);
+  const persisted = src.kind === "dm" ? Number(c.inboxOffset ?? 0) : Number(((c.roomOffsets as Record<string, number> | undefined) ?? {})[src.chan!] ?? 0);
+  return Math.max(persisted, ctx.hw.get(keyOf(src)) ?? 0);
+}
+
+/** One pass. Everything that talks to the outside world is injectable, and nothing here schedules itself. */
+export async function tailOnce(
+  agentId: string,
+  opts: {
+    transport?: Transport;
+    ctx?: TailContext;
+    markerOf?: (agentId: string) => TransportMarker | null;
+    roomsOf?: () => Promise<Record<string, { members?: string[] }>>;
+  } = {},
+): Promise<TailOutcome> {
+  const out: TailOutcome = { delivered: [], held: [] };
+  const t = opts.transport ?? activeTransport();
+  if (!t || t.kind !== HERDR) return { ...out, idle: "this server's transport is not herdr — the tail is for a herdr seat's own inbox" };
+  const ctx = opts.ctx ?? newContext();
+  const refresh = ctx.tick % REFRESH_TICKS === 0;
+  ctx.tick += 1;
+
+  // A seat with NO marker re-reads it only on the refresh cadence too. The coordinator's gate found
+  // `|| !ctx.marker` here, which made a markerless seat — the exact state a vanished marker leaves —
+  // read its marker file on every tick while the stated idle cost said otherwise.
+  if (refresh) {
+    ctx.marker = (opts.markerOf ?? readOwnMarker)(agentId);
+    if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms !== false) {
+      try {
+        const all = await (opts.roomsOf ?? getRooms)();
+        ctx.rooms = Object.entries(all ?? {}).filter(([, r]) => (r?.members ?? []).includes(agentId)).map(([chan]) => chan);
+      } catch { ctx.rooms = []; }
+    } else {
+      ctx.rooms = [];
+    }
+  }
+  const marker = ctx.marker;
+  if (!marker || marker.transport !== HERDR) return { ...out, idle: `${agentId} has no herdr marker on this bus — nothing to type into (re-checked every ${REFRESH_TICKS} ticks)` };
+
+  const sources: Source[] = [{ kind: "dm", file: inboxFile(agentId) }, ...ctx.rooms.map((chan) => ({ kind: "room" as const, chan, file: roomFile(chan) }))];
+
+  for (const src of sources) {
+    const size = sizeOf(src.file);
+    const key = keyOf(src);
+    // ⭐ THE IDLE PATH: a source that has not grown since the last tick costs this one stat.
+    if (ctx.sizes.get(key) === size) continue;
+    ctx.sizes.set(key, size);
+    const from = await offsetOf(agentId, src, ctx);
+    if (size <= from) continue;
+
+    for (const { msg, end } of newMessagesIn(src.file, from)) {
+      if (msg.from === agentId) { ctx.hw.set(key, end); continue; }
+      const where = src.kind === "dm" ? ({ kind: "dm" } as const) : ({ kind: "room", chan: src.chan! } as const);
+      const rendered = await renderForPane(msg as unknown as Message, agentId, where);
+      let r: { delivered: boolean; error?: string; verified?: boolean; safeToRetry?: boolean; outcome?: string };
+      try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, safeToRetry: false, error: (e as Error).message }; }
+      if (!r.delivered && r.safeToRetry === true) {
+        // HELD: the transport sent NO key (no ready input box, a draft, a dialog, an unreadable pane).
+        // Nothing moves and the message is retried next tick, which costs only a screen read. Stop
+        // this source so no later message is typed past one that did not land.
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: r.error ?? "held — nothing was typed" });
+        ctx.sizes.delete(key); // force a re-read next tick
+        break;
+      }
+      // ⛔ ANYTHING SHORT OF A VERIFIED DELIVERY DOES NOT MOVE THE PERSISTENT CURSOR (⟨q-15d763dc⟩).
+      // Keys may have reached the pane (text typed, an Enter pressed) without the screen proving the
+      // message was submitted, so it stays owed on disk: read_messages still serves it and a restart
+      // re-offers it. The in-process high-water mark alone stops it being re-typed every tick, since
+      // re-typing a message that may already be sitting in the box is the paste loop in another coat.
+      // A throw lands here too: nothing says whether a key went out before it.
+      if (!r.delivered || r.verified !== true) {
+        ctx.hw.set(key, end);
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: `${r.outcome ?? (r.delivered ? "unverified" : "not delivered")} — ${r.error ?? "not verified"}; the persistent cursor was not moved (q-15d763dc)` });
+        break;
+      }
+      // It landed and was verified. Record that in-process FIRST, so a cursor write that fails
+      // cannot turn one delivery into a paste loop, then persist exactly past this line.
+      ctx.hw.set(key, end);
+      const persisted = await advancePushCursor(agentId, where, end);
+      out.delivered.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? "") });
+      if (!persisted) {
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: "delivered, but the push cursor could not be written — held in memory so it is not re-typed; a restart before the next successful write may type it once more" });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+// ─── the per-process registry of running tails ─────────────────────────────
+
+type TailRecord = {
+  agentId: string;
+  startedAt: string;
+  ticks: number;
+  delivered: number;
+  held: number;
+  lastTickAt: string | null;
+  lastWhy: string | null;
+  stop: () => void;
+};
+const running = new Map<string, TailRecord>();
+
+/** What `capabilities` reports: the tails THIS PROCESS is actually running, not the ones it could run. */
+export function herdrTailState(): { agentId: string; running: true; startedAt: string; ticks: number; delivered: number; held: number; lastTickAt: string | null; lastWhy: string | null }[] {
+  return [...running.values()].map(({ stop: _stop, ...r }) => ({ ...r, running: true as const }));
+}
+
+export function stopHerdrTail(agentId: string): boolean {
+  const r = running.get(agentId);
+  if (!r) return false;
+  r.stop();
+  running.delete(agentId);
+  return true;
+}
+export function stopAllHerdrTails(): void {
+  for (const id of [...running.keys()]) stopHerdrTail(id);
+}
+
+/**
+ * Start the tail for `agentId` if this server's transport is herdr. IDEMPOTENT: a second bind of
+ * the same agent in the same process returns `running: true, started: false`.
+ *
+ * ⛔ NEVER OVERLAPS ITSELF: a tick still typing when the timer fires would interleave two pastes
+ * into one pane; the guard is one in-flight flag, because the next tick re-reads the cursor.
+ */
+export function ensureHerdrTail(
+  agentId: string,
+  opts: { transport?: Transport; pollMs?: number; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
+): { started: boolean; running: boolean; why: string } {
+  const t = opts.transport ?? activeTransport();
+  if (!t || t.kind !== HERDR) return { started: false, running: false, why: `transport is ${t?.kind ?? "unwired"}, not herdr — a tmux seat is woken by its pusher` };
+  if (running.has(agentId)) return { started: false, running: true, why: "already tailing this agent in this process" };
+  const ctx = newContext();
+  const run = opts.tail ?? ((id: string, c: TailContext) => tailOnce(id, { transport: t, ctx: c }));
+  const rec: TailRecord = { agentId, startedAt: new Date().toISOString(), ticks: 0, delivered: 0, held: 0, lastTickAt: null, lastWhy: null, stop: () => {} };
+  let inFlight = false;
+  const timer = setInterval(() => {
+    if (inFlight) return;
+    inFlight = true;
+    void run(agentId, ctx)
+      .then((o) => {
+        rec.ticks += 1;
+        rec.lastTickAt = new Date().toISOString();
+        rec.delivered += o.delivered.length;
+        rec.held += o.held.length;
+        rec.lastWhy = o.held.at(-1)?.why ?? o.idle ?? null;
+      })
+      .catch((e) => { rec.lastWhy = `tick threw: ${(e as Error).message}`; })
+      .finally(() => { inFlight = false; });
+  }, opts.pollMs ?? DEFAULT_POLL_MS);
+  timer.unref?.(); // optional-call: `unref` is absent on some host timer shims, and a server that cannot unref its tail must still start it
+  rec.stop = () => clearInterval(timer);
+  running.set(agentId, rec);
+  return { started: true, running: true, why: `tailing ${agentId}'s inbox and rooms every ${opts.pollMs ?? DEFAULT_POLL_MS}ms` };
+}
+
+/** The hook the server calls at EVERY identity binding — `join`, a gated first claim, or the env var. */
+export function startTailOnBind(agentId: string, log: (line: string) => void = (l) => console.error(l)): void {
+  const r = ensureHerdrTail(agentId);
+  if (r.started) log(`[agent-coord-mcp] herdr tail: ${r.why}`);
+}

package/src/tools/jsonl-offsets.ts

@@ -0,0 +1,29 @@
+/**
+ * Messages appended to a JSONL bus file after byte `from`, each with the absolute byte offset just
+ * past its own line. Shared by the send-time herdr path and the seat's own tail, so both agree on
+ * exactly which bytes a delivery covers — a second reader would be a second truth about where a
+ * seat's cursor may move.
+ *
+ * A partial trailing line is left for the next read rather than guessed at, and a line that is not
+ * JSON is skipped with the offset moving past it.
+ */
+import { readFileSync } from "node:fs";
+
+export type OffsetMessage = { msg: Record<string, unknown>; end: number };
+
+export function newMessagesIn(file: string, from: number): OffsetMessage[] {
+  let buf: Buffer;
+  try { buf = readFileSync(file); } catch { return []; }
+  const out: OffsetMessage[] = [];
+  let pos = Math.min(Math.max(0, from), buf.length);
+  while (pos < buf.length) {
+    const nl = buf.indexOf(0x0a, pos);
+    if (nl === -1) break;
+    const line = buf.subarray(pos, nl).toString("utf8");
+    const end = nl + 1;
+    pos = end;
+    if (!line.trim()) continue;
+    try { out.push({ msg: JSON.parse(line), end }); } catch { /* not a message; the offset moves past it */ }
+  }
+  return out;
+}

package/src/tools/messaging.ts

@@ -20,6 +20,9 @@ import { readLog } from "./logwatch.js";
 // `dist/`, so this resolves the same in the built package as in source.
 // @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
 import { priorDeliveries, replayInfo } from "../../hooks/replay.mjs";
+// ⟨q-e5cb3538⟩ The pane-unsafe byte class is single-sourced there too, shared with the renderer.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { findControlByte } from "../../hooks/control-bytes.mjs";
 import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
@@ -344,6 +347,23 @@ export async function sendMessageTool(args: {
   const scribeCheck = checkVerdictScribe(args.from, args.record);
   if (!scribeCheck.ok) return { ok: false as const, error: scribeCheck.error };
 
+  // ⟨q-e5cb3538⟩ — INGRESS POLICY: REFUSE, don't rewrite. A control byte in content is a
+  // keystroke in every pane the message is typed into (CR submits, ESC interrupts, ETX is
+  // Ctrl-C). Refused rather than silently escaped because the stored message is what gets
+  // cited and replayed; a rewrite would make it differ from what the sender wrote, and the
+  // sender is the only party who can say what the byte was for. Line feed and tab pass.
+  // Render-time escaping (hooks/tier.mjs) still covers history stored before this check.
+  const control = findControlByte({ from: args.from, to: args.to, room: args.room, text: args.text, record: args.record, repo: args.repo });
+  if (control) {
+    return {
+      ok: false as const,
+      error:
+        `refused: '${control.path}' carries a control character (${control.escape}) at offset ${control.offset}. ` +
+        "Delivered to a pane it would be typed as a keystroke in the recipient's session. " +
+        "Remove it, or write it out visibly (e.g. \\r); quoted external text (PR bodies, commit messages) is the usual carrier. Nothing was written.",
+    };
+  }
+
   // A `done` must cite the work it claims. Presence and shape only — resolving
   // the ref against gh/git is a consumer's job, and the send path makes no
   // network calls. Rejected as a value, not a throw, mirroring the