agent-coord-mcp 0.26.24 → 0.26.26

package/scripts/stop-agent.sh

@@ -1,10 +1,14 @@
 #!/usr/bin/env bash
-# stop-agent.sh — tear down an agent spawned by spawn-agent.sh.
-# Kills the tmux session and the tmux-pusher daemon.
+# stop-agent.sh — tear down a `coord-<id>` tmux session and its `pusher-<id>.pid`.
+#
+# ⟨q-ec020f6a⟩: spawn-agent.sh (the LOCAL tmux-push spawner) is gone, but this script is
+# generic over the pid-file/session-name convention, not over which pusher wrote it — and
+# coord-node.sh (the REMOTE onboarding path, still fully supported) uses the same
+# convention and documents this script as its own teardown. Kept for that reason.
 #
 # Usage:
-#   scripts/stop-agent.sh --id frontend
-#   scripts/stop-agent.sh --id frontend --dir /custom/coord/dir
+#   scripts/stop-agent.sh --id worker-2
+#   scripts/stop-agent.sh --id worker-2 --dir /custom/coord/dir
 
 set -euo pipefail
 

package/src/capabilities.ts

@@ -33,25 +33,39 @@
  * Probes call behaviour. The version travels beside the answer as CONTEXT and
  * is labelled as such.
  */
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { prRefsIn } from "./tools/record-events.js";
 import { EVENT_KIND_IDS } from "./tools/event-kinds.js";
 import { suggestRecordType, typedRecordMode } from "./typed-records.js";
 import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
 import { recordAuthorityFor } from "./roles.js";
+// ⟨q-e5cb3538⟩ The renderer and the byte class live in hooks/, shared with both pushers.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { injectLine } from "../hooks/tier.mjs";
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { findControlByte } from "../hooks/control-bytes.mjs";
+// ⟨q-15d763dc⟩ The ready-box guard's profile, as this process read it from its own env at start.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { readyProfile } from "../hooks/submit.mjs";
 import { subscriptionHealth } from "./tools/events.js";
 import {
   configuredTransport,
   runningTransport,
   isTmuxKind,
   targetOf,
+  herdrMarkerPid,
   type TransportKind,
 } from "./transports/index.js";
-import { readAllTransportMarkers } from "./tools/registry.js";
+import { readAllTransportMarkers, markerHoldsLiveProcess } from "./tools/registry.js";
 import { queueWriteSchema } from "./tools/queue-write.js";
 import { treeProvenance } from "./tools/tree-provenance.js";
 import { detectSpread } from "./server-spread.js";
+import { answeringServerIdentity } from "./tools/registry.js";
 import { HerdrTransport, herdrKeyName } from "./transports/herdr.js";
 import { tickVerdict } from "./tools/tick.js";
+import { ensureHerdrTail, herdrTailState, newContext, newMessagesIn, stopHerdrTail } from "./tools/herdr-tail.js";
 import { HERDR, TICK_READS_AS, TICK_STORED_AS, type TickState } from "./transports/types.js";
 
 export type ProbeResult = {
@@ -302,6 +316,78 @@ const PROBES: Probe[] = [
       return { present, evidence: `"⛔ Blocked — was 🚧 …" in flight: ${blocked} (0.26.21 said true) · "🔍 In Review": ${review} -> present=${present}` };
     },
   },
+  {
+    // ⛔ A HERDR SEAT'S OWN SERVER TAILS ITS INBOX. The first version of this probe checked
+    // `typeof startHerdrTail === "function"` — which read PRESENT on six seats while the tail ran
+    // on none, the exact lie this verb exists to refuse. It now STARTS a tail against a scripted
+    // herdr transport and asserts the process registry reports it running, is idempotent on a
+    // second bind, and reports it gone after a stop — plus the line reader's byte offsets, which
+    // are what stop a later held message being skipped. Runtime truth for THIS seat is reported
+    // separately, under `herdrTail`, because a probe answers "can this build" and not "is it".
+    id: "herdr-inbox-tail",
+    since: "0.26.25",
+    run: () => {
+      const probeId = `__probe-herdr-tail-${process.pid}`;
+      const scripted = { kind: HERDR } as unknown as Parameters<typeof ensureHerdrTail>[1] extends infer O ? O extends { transport?: infer T } ? T : never : never;
+      const dir = mkdtempSync(path.join(tmpdir(), "probe-tail-"));
+      try {
+        const first = ensureHerdrTail(probeId, { transport: scripted, pollMs: 3_600_000, tail: async () => ({ delivered: [], held: [] }) });
+        const again = ensureHerdrTail(probeId, { transport: scripted, pollMs: 3_600_000, tail: async () => ({ delivered: [], held: [] }) });
+        const seen = herdrTailState().some((s) => s.agentId === probeId && s.running);
+        const stopped = stopHerdrTail(probeId);
+        const gone = !herdrTailState().some((s) => s.agentId === probeId);
+        const f = path.join(dir, "inbox.jsonl");
+        const a = `${JSON.stringify({ id: "a" })}\n`;
+        writeFileSync(f, `${a}${JSON.stringify({ id: "b" })}\n{"id":"hal`);
+        const read = newMessagesIn(f, 0);
+        const offsets = read.map((m) => m.end).join(",") === `${Buffer.byteLength(a)},${Buffer.byteLength(a) + Buffer.byteLength(`${JSON.stringify({ id: "b" })}\n`)}`;
+        const present = first.started && !again.started && again.running && seen && stopped && gone && read.length === 2 && offsets;
+        return { present, evidence: `ensureHerdrTail started=${first.started} · second bind started=${again.started} running=${again.running} · registry running=${seen} · stop=${stopped} gone=${gone} · reader ${read.length} whole lines with exact end offsets=${offsets} -> present=${present}` };
+      } finally {
+        stopHerdrTail(probeId);
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  },
+  {
+    // ⛔⛔ ⟨q-cdb5b007⟩ — the HTTP daemon started NO tails at all, so any seat one message behind
+    // was permanently and silently deaf. This probe exists because the PREVIOUS probe could not
+    // see that: it starts a tail by calling `ensureHerdrTail` directly, which is exactly what
+    // production never did under token auth. A capability that only the test calls is not present.
+    //
+    // Probed here: a tail started the way `startTailOnBind` now starts it types NOTHING that
+    // predates it. That is the half a seat can check about ITSELF; whether this build's auth path
+    // reaches it is reported at runtime under `herdrTail`, which must be non-empty on a live
+    // daemon. Label and code disagree by design — `versionLabel` reads package.json on disk.
+    id: "http-prebound-starts-tail-at-eof",
+    since: "0.26.26",
+    run: () => {
+      const probeId = `__probe-tail-eof-${process.pid}`;
+      const dir = mkdtempSync(path.join(tmpdir(), "probe-tail-eof-"));
+      try {
+        const seeded = newContext(true);
+        const inherited = newContext(false);
+        const hasSeedFields = typeof seeded.seedEof === "boolean" && seeded.seeded instanceof Set;
+        // A seeded context adopts EOF on first sight of a source; an inherited one does not.
+        const scripted = { kind: HERDR } as unknown as NonNullable<Parameters<typeof ensureHerdrTail>[1]>["transport"];
+        const seededStart = ensureHerdrTail(probeId, {
+          transport: scripted,
+          pollMs: 3_600_000,
+          seedEof: true,
+          tail: async () => ({ delivered: [], held: [] }),
+        });
+        const running = herdrTailState().some((s) => s.agentId === probeId && s.running);
+        const present = hasSeedFields && seeded.seedEof === true && inherited.seedEof === false && seededStart.started && running;
+        return {
+          present,
+          evidence: `newContext(true).seedEof=${seeded.seedEof} · newContext(false).seedEof=${inherited.seedEof} · per-source seeded set=${seeded.seeded instanceof Set} · ensureHerdrTail({seedEof}) started=${seededStart.started} running=${running} -> present=${present}`,
+        };
+      } finally {
+        stopHerdrTail(probeId);
+        rmSync(dir, { recursive: true, force: true });
+      }
+    },
+  },
   {
     // ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — the external tick, probed by CALLING the code that
     // decides what a reading MEANS (every probe here is synchronous, so the async read is
@@ -342,6 +428,72 @@ const PROBES: Probe[] = [
       return { present, evidence: `HerdrTransport.kind=${scripted.kind} · scripted pane_not_found -> paneExists=${exists} · herdrKeyName("C-u").ok=${key.ok} -> present=${present}` };
     },
   },
+  {
+    // ⟨q-e5cb3538⟩ (0.26.25) — a control byte in message content never reaches a pane as a
+    // keystroke: the renderer every push path uses shows it as a visible escape, and a new send
+    // carrying one is refused at ingress. Measured on qa's payload (CR, ESC[201~, ETX) plus DEL
+    // and C1, rendered through THIS process's hooks — a seat whose server predates the fix answers
+    // false here, which is the question a release is delivered by.
+    id: "pane-render-neutralizes-controls",
+    since: "0.26.25",
+    run: () => {
+      const body = "X1\rX2\x1b[201~X3\x03X4\x7f\u0085";
+      const line = String(injectLine({ ts: 0, tag: "DM", from: "probe", text: body }));
+      const leaked = (line.match(/[\x00-\x09\x0b-\x1f\x7f\u0080-\u009f]/g) ?? []).length;
+      const visible = line.includes("X1\\rX2\\x1b[201~X3\\x03X4\\x7f\\u0085");
+      const refused = findControlByte({ text: body }) !== null && findControlByte({ text: "ok\n\tok" }) === null;
+      const present = leaked === 0 && visible && refused;
+      return { present, evidence: `rendered qa's payload + DEL + C1 -> leaked ${leaked} control byte(s) · escapes visible=${visible} · ingress refuses it and passes LF/TAB=${refused} -> present=${present}` };
+    },
+  },
+  {
+    // ⟨q-abd88dd4⟩ — a herdr marker's pid is chosen for the pre-herdr readers that cannot be
+    // patched: 1 only where this process may not signal pid 1 (EPERM), 0 otherwise, and this
+    // build never reads it as a process. Both functions are new in 0.26.25.
+    id: "herdr-marker-survives-pre-herdr-readers",
+    since: "0.26.25",
+    run: () => {
+      const eperm = () => { const e = new Error("EPERM") as NodeJS.ErrnoException; e.code = "EPERM"; throw e; };
+      const notSignalable = herdrMarkerPid(eperm).pid;
+      const signalable = herdrMarkerPid(() => true).pid;
+      const holds = markerHoldsLiveProcess({ agentId: "probe", transport: HERDR, pid: 1, since: 0 });
+      const present = notSignalable === 1 && signalable === 0 && holds === false;
+      return { present, evidence: `kill(1,0) EPERM -> pid ${notSignalable} · kill(1,0) permitted (root/container) -> pid ${signalable} · herdr marker pid 1 holds a live process: ${holds} -> present=${present}` };
+    },
+  },
+  {
+    // ⟨q-3cd5a77d⟩ — the result word counts only in the CLAIM position. A seat on an older server
+    // reads the #359 routing header (PASS in the PR title) as the coordinator gating it PASS.
+    id: "gate-claim-needs-claim-position",
+    since: "0.26.25",
+    run: () => {
+      const sha = "0826519e043add993c5d757908c1903239542160";
+      const line = (text: string) => JSON.stringify({ ts: 1, from: "probe", text, record: { type: "go", payload: {}, cites: [{ kind: "pr", ref: "#359" }] } });
+      const routing = gateClaimsIn(line(`GATE, prioritised: #359 (test-all prints PASS after FAILED) @ ${sha}`), "359", sha).length;
+      const typed = gateClaimsIn(line(`QA GATE — **PASS** @ \`${sha}\``), "359", sha).length;
+      const present = routing === 0 && typed === 1;
+      return { present, evidence: `routing header with PASS in the title -> ${routing} claim(s) · typed QA GATE — **PASS** @ sha -> ${typed} -> present=${present}` };
+    },
+  },
+  {
+    // ⟨q-18a719c5⟩ The spread can place a seat at all: the identity THIS server stamps names its
+    // module (resolved by package name, through the real caller in dist/tools/registry.js), a
+    // stamp whose pid is gone reads unknown, and unknowns block AGREED but not DIVERGED. Before
+    // 0.26.25 the module resolved to undefined on every server.
+    id: "server-spread-places-seats",
+    since: "0.26.25",
+    run: () => {
+      const me = answeringServerIdentity();
+      const installed = typeof me.serverModule === "string" ? { mtime: 1_000, module: me.serverModule } : null;
+      const seat = (agentId: string, startedAt: number, pid = 101) => ({ agentId, serverPid: pid, serverStartedAt: startedAt, serverModule: me.serverModule });
+      const alive = (pid: number) => pid !== 999;
+      const stale = installed ? detectSpread([seat("gone", 2_000, 999), seat("b", 3_000)], installed, { isRunning: alive }) : null;
+      const split = installed ? detectSpread([seat("old", 500), seat("new", 3_000), { agentId: "mute" }], installed, { isRunning: alive }) : null;
+      const staleUnknown = !!stale?.uncomparable.some((u) => u.agentId === "gone" && /no longer running/.test(u.why));
+      const present = typeof me.serverModule === "string" && staleUnknown && split?.state === "DIVERGED";
+      return { present, evidence: `module ${me.serverModule ?? "UNRESOLVED"} · dead stamp -> unknown: ${staleUnknown} · split + unstamped seat -> ${split?.state ?? "n/a"} -> present=${present}` };
+    },
+  },
   {
     id: "record-authority",
     since: "0.24.0",
@@ -382,8 +534,8 @@ export type TransportCapability = {
   agrees: boolean;
   /** What was called and what came back. */
   evidence: string;
-  /** Where `configured` came from — config file, env, or the built-in default. */
-  configuredSource: "config" | "env" | "default";
+  /** Where `configured` came from — config file or env. ⟨q-ec020f6a⟩: no built-in default. */
+  configuredSource: "config" | "env";
   /**
    * MIXED FLEET, MADE LOUD (3.4). Agents whose marker names a transport other
    * than the running one. Whole-fleet is the rule; this is the code noticing
@@ -524,7 +676,7 @@ export function probeCapabilities(context: { module: string; versionLabel: strin
 
 import { resolveServerIdentity } from "./server-identity.js";
 import { seatBuildOf, installedFrom, psReader, type SeatBuild } from "./tools/seat-build.js";
-import { isInFlightStatus } from "./tools/stall.js";
+import { isInFlightStatus, gateClaimsIn } from "./tools/stall.js";
 import { parseWorkDoc, queueItemsOf, stampQueueIds } from "@davidbalzan/groundwork-seam";
 
 export const capabilitiesSchema = {} as const;
@@ -609,11 +761,24 @@ export async function seatBuilds(): Promise<{ installed: { module: string; hookP
   };
 }
 
+/**
+ * ⟨q-15d763dc⟩ Is THIS process's pane push guarded? `guarded:false` means AGENT_COORD_READY_PROFILE=none
+ * was set in this server's env at start: its pushes type into panes without checking for Claude
+ * Code's input box. Stated here so an unguarded seat is visible fleet-wide, not only in a log.
+ */
+function readyBoxState(): { profile: string; guarded: boolean; source: string; warning?: string } {
+  const p = readyProfile() as { profile: string; raw: string | null; warning?: string };
+  return { profile: p.profile, guarded: p.profile !== "none", source: "AGENT_COORD_READY_PROFILE in this process's env at start (never a message or the bus dir)", ...(p.warning ? { warning: p.warning } : {}) };
+}
+
 export async function capabilitiesTool() {
   const id = resolveServerIdentity();
   const report = probeCapabilities({ module: id.path, versionLabel: id.version });
   try {
-    return { ...report, transport: await probeTransport(), seats: await seatBuilds() };
+    // ⭐ `herdrTail` is RUNTIME truth for this process — the tails actually ticking here — kept apart
+    // from the build probe on purpose, because "this build can tail" and "this seat is tailing"
+    // are different facts and the first version of #353 reported the first as the second.
+    return { ...report, transport: await probeTransport(), herdrTail: herdrTailState(), readyBox: readyBoxState(), seats: await seatBuilds() };
   } catch (e) {
     // A THROWN TRANSPORT PROBE IS NOT A BROKEN VERB. An unknown configured value
     // refuses at startup by design, and this verb is exactly what an operator

package/src/gated-head.ts

@@ -233,8 +233,19 @@ export function gatedBy(verdicts: PassVerdict[], head: string, mergedAt: number
  * so the experiment CONFIRMS the false mechanism — whoever ran it would conclude they had
  * removed something load-bearing and got away with it. If you are removing it, the thing
  * to check is `DECLARES`, not this.
+ *
+ * ⛔ ⟨q-3cd5a77d⟩ THE RESULT WORD MUST STAND IN THE CLAIM POSITION — right after the opener, past
+ * only separators (`:` `—` `–` `-`, spaces) and an optional `**`. The first version accepted PASS or
+ * FAIL ANYWHERE before the `@`, so a ROUTING header read as a verdict:
+ *     `GATE, prioritised: #359 (⟨q-3605ede3⟩, test-all prints PASS after FAILED) @ 0826519e…`
+ * — the word was in the PR's TITLE. Bus history is permanent, so that one DM (11:19:43Z) turned
+ * `verdict-names-gater`'s live-population test red on every chain on the machine, and made
+ * `stall_check` report #359 as `reported-unscribed` with the COORDINATOR claiming PASS at its head.
+ * Measured before the change, old vs new over 126 real lines (the 61-line verdict corpus + every
+ * distinct line the old form matched on the live bus and in kit PR comments): they differ on
+ * exactly that routing line, and agree — result word and sha — on the other 125.
  */
-export const VERDICT_COMMENT = /^(?:QA GATE|\*\*GATE|GATE)\b[^\n]*?\b(PASS|FAIL)\b(?:\s*\([^)\n]*\))?[^\n]*?@\s*`?([0-9a-f]{7,40})`?/;
+export const VERDICT_COMMENT = /^(?:QA GATE|\*\*GATE|GATE)\b[\s:—–-]*(?:\*\*\s*)?(PASS|FAIL)\b[^\n]*?@\s*`?([0-9a-f]{7,40})`?/;
 
 /**
  * WHAT MAKES A VERDICT BINDING, expressed as a shape instead of a phrase: a

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);
@@ -825,8 +845,24 @@ async function main() {
   // branching in send_command or attach.
   try {
     const t = initTransportFromConfig();
-    if (t.source !== "default") {
-      console.error(`[agent-coord-mcp] transport: ${t.kind} (from ${t.source})`);
+    // ⟨q-ec020f6a⟩: no built-in default any more — every resolution has a real source, always logged.
+    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
@@ -1040,6 +1076,16 @@ async function startHttp(port: number): Promise<void> {
     const tokenMap = getTokenMap();
     if (tokenMap) {
       const agent = tokenMap.get(bearer);
+      // ⛔ THE ONLY PLACE A PRE-BOUND SEAT CAN GET A TAIL. The `startTailOnBind` sites in the tool
+      // path all sit behind `bound === undefined` — the TOFU claim. Here identity arrives already
+      // decided by the bearer, that branch is unreachable, and before this line NO tail ever
+      // started under HTTP (⟨q-cdb5b007⟩: `herdrTail: []`, and send-time delivery deferring to a
+      // tail that does not exist drops the message permanently and silently).
+      //
+      // Deliberately lazy rather than a loop over the whole token map at boot: only a seat that
+      // actually connects gets a tail, so a 20-agent map does not spawn 20 timers for seats that
+      // may not exist. Idempotent — steady state is one Map lookup per request.
+      if (agent) startTailOnBind(agent);
       return agent ? { ok: true, agent } : { ok: false };
     }
     // Advisory mode: only check the shared bearer matches.

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