agent-coord-mcp 0.26.23 → 0.26.25

package/src/gated-head.ts

@@ -207,13 +207,200 @@ export function gatedBy(verdicts: PassVerdict[], head: string, mergedAt: number
 }
 
 /**
- * The typed verdict line on a PR page (#313's grammar): `QA GATE — **PASS** @ \`sha\``
- * or the merge-time `**GATE: PASS** … @ \`sha\``. Uppercase PASS/FAIL as a whole
- * word on a line that opens with the gate marker and carries an `@ sha`. Prose
- * that says "passes", "verdict" or "FAILs" does not match — #299's shape, where
- * a PASS|FAIL substring scan would have counted an explicit non-verdict review.
+ * ⛔ #313's GRAMMAR, KEPT ONLY FOR BACKWARDS COMPATIBILITY — IT MATCHED NOTHING IN
+ * THE FIELD. `QA GATE — **PASS** @ \`sha\`` was ruled canonical and then had ZERO
+ * ADOPTION: measured against the 9 merges of 2026-09-15, it matched 0 verdict
+ * lines while all 9 merges carried one, so `unverdicted-merge` fired 9 times on 9
+ * correct merges — 100% false positive, which trains the room to ignore the one
+ * instrument protecting the convention.
+ *
+ * ⭐ THE LESSON IS WHY THIS CONSTANT IS NO LONGER THE PREDICATE: A REGEX OVER PROSE
+ * TESTS THE PHRASING, NOT THE CLAIM. The verdicts were never missing; only the
+ * agreed wording was. Nobody noticed because every verdict is read BY EYE at gate
+ * time and they all read fine — the instrument and the humans disagreed silently
+ * for a day.
+ *
+ * ⚠ SCOPE, CORRECTED: "zero adoption" IS TRUE OF A CONSUMER FLEET AND FALSE OF THIS REPO.
+ * Measured: 0 of 9 of that fleet's merges carry this grammar; 4 of 6 kit merges do, verbatim
+ * (`#342`, `#340`, `#337`, `#336`). The original write-up scoped a measurement to one
+ * consumer and stated it universally.
+ *
+ * ⛔⛔ AND DO NOT BELIEVE THIS CONSTANT IS WHAT KEEPS THAT KIT GRAMMAR WORKING — I
+ * CLAIMED THAT AND IT IS FALSE. `verdictBoundTo` → `verdictClaimsIn` NEVER references
+ * `VERDICT_COMMENT`; it survives only in the legacy `verdictShasIn`. Compatibility comes
+ * from `DECLARES` accepting the `(?:QA )?GATE\b` opener. ⇒ THE TRAP THAT MAKES THIS
+ * WORTH WRITING DOWN: deleting this constant as dead code leaves the kit grammar working,
+ * 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[\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
+ * DISPOSITION and a SHA, on ONE LINE, with the disposition ahead of the `@`. The
+ * caller then decides bindingness by comparing that sha to the head it cares
+ * about — the claim, not the header.
+ *
+ * Derived from the five spellings actually in the field on 2026-09-15, none of
+ * which the constant above matches:
+ *   `## QA verdict — DONE: PASS \`#970\` @ \`sha\` · mode: full-local · base …`
+ *   `## QA verdict — DONE: CONTENT PASS \`#964\` @ \`sha\``
+ *   `## QA verdict — DONE: READINESS RELEASED \`#964\` @ \`sha\``
+ *   `## QA-2 — FULL PASS (content + readiness) @ \`sha\``
+ *   `## qa-2 — CONTENT PASS (re-bind) @ \`sha\` · READINESS NOT CLEAR`
+ *
+ * ⛔ THE HALVES ARE DISTINGUISHED, BECAUSE A CONTENT PASS IS NOT A CLEARANCE. It
+ * says so in its own body ("READINESS NOT ESTABLISHED — do not merge yet"), so
+ * counting it as a whole verdict would license exactly the merge it forbids. A
+ * caller wanting "was this clear to merge" needs a WHOLE verdict, or BOTH halves.
+ *
+ * ⛔ ORDER MATTERS IN THE CLASSIFIER: `CONTENT PASS` and `READINESS RELEASED` are
+ * tested before bare `PASS`, and `READINESS NOT CLEAR`/`NOT ESTABLISHED` must not
+ * read as a readiness half — the live `## qa-2 — CONTENT PASS (re-bind) @ sha ·
+ * READINESS NOT CLEAR` line carries both phrases and is a CONTENT half only.
+ */
+export type VerdictClaim = { result: string; sha: string; half: "whole" | "content" | "readiness" };
+const NEGATED_READINESS = /READINESS\s+(?:NOT|IS\s+NOT)\b/i;
+/**
+ * ⛔ THE LINE MUST DECLARE, NOT REMARK — and this anchor is here because removing it
+ * BROKE THE AIDE'S #299 CONTROL, which caught it immediately. That control's sharpest
+ * fixture is `Looks like a PASS to me — see the run @ \`sha\` for the log; not a gate.`:
+ * uppercase PASS, an `@`, and the MERGED HEAD's own sha. Disposition-plus-bound-sha alone
+ * counts it, and a chat remark then silences the check for a genuinely unverdicted merge.
+ *
+ * So a claim is a HEADING (every live verdict on 2026-09-15 is `## …`) or the legacy gate
+ * opener. That is still structure rather than phrasing — what it requires is that someone
+ * DECLARED a disposition, not that they used a particular sentence — and it is the part of
+ * #313's grammar worth keeping: `QA GATE` was the wrong half to demand, `is a declaration`
+ * was the right one.
+ */
+const DECLARES = /^\s*(?:#{1,6}\s+|\*\*(?:QA )?GATE|(?:QA )?GATE\b)/;
+/** An explicit disclaimer on the same line is dispositive — the author says it is not one. */
+const DISCLAIMED = /\bnot a (?:gate|verdict)\b/i;
+
+/**
+ * ⛔⛔ A WITHDRAWAL IS NOT THE VERDICT IT WITHDRAWS, AND THE NAIVE READING IS THE DANGEROUS ONE.
+ * A consumer fleet's gate seat posted these on one of its PRs; both bound as a clean PASS before this line
+ * existed:
+ *     `## ⛔ VOIDING my PASS-HOLD @ <sha> — that head is two moves dead`
+ *     `## ⛔ VOIDING my PASS @ <sha>`
+ * A line that revokes a verdict names that verdict — so matching the disposition word inside it
+ * turns a RETRACTION into a CLEARANCE. That is a FALSE NEGATIVE in a watchdog, which is
+ * indistinguishable from a clean run: `unverdicted-merge` would stay silent on a PR merged after
+ * its verdict was voided, which is precisely the merge it exists to catch.
+ *
+ * ⛔⛔ AND POSITION IS THE DISCRIMINATOR, NOT PRESENCE — the first version tested this pattern
+ * ANYWHERE on the line and failed in the OPPOSITE direction. A verdict that REPLACES an earlier
+ * one routinely says so in its own header, which is the practice that keeps a superseded verdict
+ * VISIBLE instead of silently edited:
+ *     `## QA GATE — **FAIL** @ <sha> — superseding my CONTENT PASS above`   ← verbatim, a consumer fleet's PR
+ * Discarding that one makes `unverdicted-merge` FIRE ON A PROPERLY GATED MERGE — and it
+ * concentrates where gating was MOST active, because a PR whose verdict got corrected is one that
+ * received MORE scrutiny. The instrument would go loudest exactly where it is least needed.
+ *
+ * ⇒ IN A WITHDRAWAL THE VERB PRECEDES THE DISPOSITION; IN A SUPERSEDING VERDICT THE DISPOSITION
+ * COMES FIRST. qa-2's shape, and it is measured rather than reasoned: across ALL 124 verdict-shaped
+ * lines in both repos (101 of them declaration-shaped), exactly TWO carry a revocation verb, and
+ * they split correctly by position — 1 withdrawal, 1 superseding verdict, 99 plain verdicts.
+ *
+ * ⚠ THE RESIDUAL, STATED WITH ITS DENOMINATOR RATHER THAN LEFT IMPLIED: `PASS @ <sha> —
+ * SUPERSEDED, see below` puts the verb after the disposition and would be ACCEPTED. qa-2 raised it
+ * as its own invention and flagged it as not field-observed; the corpus agrees — ZERO of 124. It is
+ * also partly self-correcting, since whatever supersedes it binds the same sha later.
  */
-export const VERDICT_COMMENT = /^(?:QA GATE|\*\*GATE|GATE)\b[^\n]*?\b(PASS|FAIL)\b(?:\s*\([^)\n]*\))?[^\n]*?@\s*`?([0-9a-f]{7,40})`?/;
+const REVOCATION_VERB = /\b(?:VOID(?:ING|ED)?|WITHDRAW(?:N|ING)?|RETRACT(?:ED|ING)?|SUPERSED(?:ED|ING|ES))\b/i;
+/** True only when the revocation verb comes BEFORE the disposition it names. */
+function isWithdrawal(line: string, dispositionIndex: number): boolean {
+  const verb = REVOCATION_VERB.exec(line);
+  return verb !== null && verb.index < dispositionIndex;
+}
+
+/**
+ * ⛔ `PASS-HOLD` IS A DOCUMENTED DO-NOT-MERGE VERDICT (`coord-qa/SKILL.md:71,74`) AND `\bPASS\b`
+ * MATCHED INSIDE IT, because `-` is a non-word character. So the one verdict type whose entire
+ * meaning is "do not merge" classified as a clearance and BOUND.
+ * ⚠ It had not yet fired, and that was LUCK: qa-2's own `#974` PASS-HOLD missed only because the
+ * head moved and the sha stopped agreeing. Nothing in the classifier prevented it.
+ */
+const HOLD = /\bPASS-HOLD\b/i;
+
+/**
+ * ⭐ FOUND BY THE CORPUS, NOT BY A GATE — the fourth non-clearance form, and the first one this
+ * suite caught itself rather than a reviewer catching it:
+ *     `## QA — **READINESS REFUSED** @ <sha> · the CONTENT PASS above still stands`   (a consumer fleet's PR)
+ * ⚠ IT ALREADY BEHAVED CORRECTLY, AND ONLY BY ACCIDENT: `READINESS REFUSED` is not a disposition,
+ * and the `CONTENT PASS` it mentions sits AFTER the `@ <sha>`, so no claim matched. Reorder that
+ * sentence — `the CONTENT PASS above still stands @ <sha>` — and the refusal would have BOUND as a
+ * content half. Naming it makes the behaviour a decision instead of a word-order coincidence.
+ */
+const REFUSED = /\bREADINESS\s+REFUSED\b/i;
+/** A disposition ahead of an `@ sha` on the same line. The sha's binding is the caller's test. */
+const CLAIM_LINE = /\b(READINESS\s+RELEASED|CONTENT\s+PASS|FULL\s+PASS|PASS-HOLD|PASS|FAIL)\b[^\n]*?@\s*`?([0-9a-f]{7,40})`?/i;
+export function verdictClaimsIn(comments: { body: string }[]): VerdictClaim[] {
+  const out: VerdictClaim[] = [];
+  for (const c of comments) {
+    for (const line of String(c.body ?? "").split("\n")) {
+      // ⛔ A HOLD IS A NON-CLEARANCE THAT NAMES ITS OWN DISPOSITION, so it is rejected outright.
+      if (!DECLARES.test(line) || DISCLAIMED.test(line) || HOLD.test(line) || REFUSED.test(line)) continue;
+      const m = CLAIM_LINE.exec(line);
+      if (!m) continue;
+      // ⛔ A WITHDRAWAL IS REJECTED BY POSITION, NOT BY PRESENCE — see isWithdrawal. Testing the
+      // verb anywhere on the line discards the superseding verdicts that carry it AFTER the
+      // disposition, which fires the watchdog on properly gated merges.
+      if (isWithdrawal(line, m.index)) continue;
+      const word = m[1]!.toUpperCase().replace(/\s+/g, " ");
+      const sha = m[2]!;
+      if (word === "READINESS RELEASED") {
+        out.push({ result: "PASS", sha, half: "readiness" });
+      } else if (word === "CONTENT PASS") {
+        out.push({ result: "PASS", sha, half: "content" });
+      } else if (word === "FAIL") {
+        out.push({ result: "FAIL", sha, half: "whole" });
+      } else {
+        // bare PASS / FULL PASS — a whole verdict unless the same line withholds readiness
+        out.push({ result: "PASS", sha, half: NEGATED_READINESS.test(line) ? "content" : "whole" });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Is there a verdict BOUND TO `head` — a whole one, or both halves? This is the
+ * question `unverdicted-merge` actually asks, and it is the seam #964 exposed:
+ * that PR published CONTENT PASS and READINESS RELEASED as two separate comments,
+ * so a rule scoped to a whole verdict misses a merge that was fully gated.
+ *
+ * ⭐ A SUPERSEDED VERDICT CANNOT SATISFY THIS, BY CONSTRUCTION RATHER THAN BY A
+ * SPECIAL CASE. #965's FAIL cited `ab58f9455` — an object that does not exist —
+ * and was corrected in a later comment. Requiring agreement with the head that
+ * MERGED means a sha naming any other tree (wrong, stale, or nonexistent) simply
+ * does not bind. No "is this superseded" heuristic is needed and none is used.
+ */
+export function verdictBoundTo(comments: { body: string }[], head: string): { bound: boolean; why: string } {
+  const claims = verdictClaimsIn(comments).filter((v) => shaAgrees(v.sha, head));
+  const whole = claims.find((v) => v.half === "whole");
+  if (whole) return { bound: true, why: `${whole.result} bound to ${head.slice(0, 7)}` };
+  const content = claims.some((v) => v.half === "content");
+  const readiness = claims.some((v) => v.half === "readiness");
+  if (content && readiness) return { bound: true, why: `CONTENT PASS + READINESS RELEASED bound to ${head.slice(0, 7)} (split halves)` };
+  if (content) return { bound: false, why: `only a CONTENT half at ${head.slice(0, 7)} — readiness never released, which is the half that clears a merge` };
+  if (readiness) return { bound: false, why: `only a READINESS half at ${head.slice(0, 7)} — no content verdict` };
+  return { bound: false, why: `no disposition bound to ${head.slice(0, 7)}` };
+}
+
 export function verdictShasIn(comments: { body: string }[]): { result: string; sha: string }[] {
   const out: { result: string; sha: string }[] = [];
   for (const c of comments) {

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/away.ts

@@ -92,6 +92,18 @@ export const COVERAGE_THRESHOLD = "EVERY in-flight lane the clock scores must be
  * carries the reading's age and labels it stale past this many minutes.
  */
 export const COVERAGE_STALE_MINUTES = 60;
+/**
+ * ⟨q-1c95f7d4⟩ 5.4 — the tick's own sentence for the announcement and the refusal. A fleet
+ * with NO tick source says so (that is this fleet today: six tmux seats, zero herdr), and a
+ * fleet with a source that answered for nobody says BLIND rather than saying nothing.
+ */
+export const tickSentence = (t?: AwayTick): string => {
+  if (!t || t.seats === 0) return " No external tick: no seat has an observer to ask, so every lane above was measured from its branch and the board alone.";
+  if (t.readable === 0) return ` External tick BLIND: ${t.seats} seat(s) have an observer and none answered — a source that cannot be read is not a quiet fleet.`;
+  const states = Object.entries(t.states).map(([k, v]) => `${v} ${k}`).join(", ");
+  return ` External tick: ${t.readable}/${t.seats} seat(s) answered${states ? ` (${states})` : ""} — evidence about the seats, beside the branch axes, never instead of them.`;
+};
+
 export const fmtAge = (ms: number): string => (ms < 60_000 ? `${Math.max(0, Math.round(ms / 1000))}s` : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m` : ms < 86_400_000 ? `${Math.floor(ms / 3_600_000)}h` : `${Math.floor(ms / 86_400_000)}d`);
 export function coverageAgeOf(coverage: { at: string }, now = Date.now()): { ageMs: number | null; stale: boolean; label: string } {
   const at = Date.parse(coverage.at);
@@ -103,10 +115,28 @@ export function coverageAgeOf(coverage: { at: string }, now = Date.now()): { age
 /** Met when nothing scored is unseen — an empty board (0 of 0) is idle, not blind, and needs no special case. */
 export const meetsCoverageThreshold = (c: { checked: number; measurable: number }): boolean => c.measurable >= c.checked;
 
+/**
+ * ⟨q-1c95f7d4⟩ Task 5.4 — WHAT THE EXTERNAL TICK CONTRIBUTES TO THE AWAY PRECONDITION.
+ *
+ * The precondition asks what the clock could actually SEE. A seat observed from OUTSIDE
+ * this process — herdr answering `idle | working | blocked` for its pane — is seen in a way
+ * a pid and a branch cannot manage: it is the only signal here that separates a thinking
+ * lane from a wedged one. So a readable tick counts as measured, through `stall_check`'s
+ * own coverage arithmetic, and nothing is special-cased here.
+ *
+ * ⛔ WHAT IS NOT DONE, DELIBERATELY: a tick NEVER raises coverage for a seat the branch
+ * axes could not measure into "observed enough to go away on". It credits the seat it read
+ * and nothing else, and a fleet with a tick source that answered for NOBODY is reported as
+ * blind — `0 of N readable` is the blind case this verb exists to refuse, not a quiet one.
+ */
+export type AwayTick = { seats: number; readable: number; states: Record<string, number>; note: string };
+
 export type AwayCoverage = {
   checked: number;
   measurable: number;
   blind: string[];
+  /** ⟨q-1c95f7d4⟩ the external tick behind this coverage number, named so the announcement can say what watched the fleet. */
+  tick?: AwayTick;
   /** ⟨q-5d1c8e04⟩ — standing seats on the board: present, not scored, and therefore not blind. */
   roles?: number;
   /** Lanes that declare no per-agent branch: out of the population by their own statement. */
@@ -220,6 +250,7 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
   try {
     const r = (await stallCheckTool({ repo })) as unknown as {
       ok?: boolean; checked?: number; measurable?: number; blind?: string[]; roles?: unknown[]; deliberate?: unknown[];
+      tick?: { seats?: unknown[]; readable?: number; states?: Record<string, number>; note?: string };
       boardParse?: { readable: boolean; rowsPresent: number; rowsParsed: number; why: string };
     };
     // ⟨q-3d82f1a9⟩ — AN UNREADABLE BOARD IS A NAMED STATE, not "could not measure".
@@ -237,6 +268,9 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
       checked: r.checked ?? 0,
       measurable: r.measurable ?? 0,
       blind: r.blind ?? [],
+      tick: r.tick
+        ? { seats: r.tick.seats?.length ?? 0, readable: r.tick.readable ?? 0, states: (r.tick.states ?? {}) as Record<string, number>, note: r.tick.note ?? "" }
+        : undefined,
       roles: r.roles?.length ?? 0,
       deliberate: r.deliberate?.length ?? 0,
       at: new Date().toISOString(),
@@ -352,7 +386,8 @@ export async function coordAwayTool(args: {
           `"The clock ran" and "the fleet is observed" are different facts, and this verb must not treat the first as the second. ` +
           `The usual cause is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref: a path resolves for ` +
           `git and measures the wrong thing, so the check reports it unmeasurable rather than guessing. Fix those cells and ` +
-          `coverage returns. If you mean to go anyway, pass acknowledgeBlindFleet:true — it is recorded in the state and in the announcement.`,
+          `coverage returns. If you mean to go anyway, pass acknowledgeBlindFleet:true — it is recorded in the state and in the announcement.` +
+          tickSentence(coverage.tick),
       };
     }
 
@@ -382,7 +417,8 @@ export async function coordAwayTool(args: {
         `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
         `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
         `Decisions logged to ${args.decisionLog}. ` +
-        `Stall coverage ${coverage.measurable}/${coverage.checked}${!meetsCoverageThreshold(coverage) ? ` — ACKNOWLEDGED BLIND${coverage.measurable === 0 ? ": the clock runs and sees nothing" : ""}${coverage.blind.length ? ` on: ${coverage.blind.join(", ")}` : ""}` : ""}.`,
+        `Stall coverage ${coverage.measurable}/${coverage.checked}${!meetsCoverageThreshold(coverage) ? ` — ACKNOWLEDGED BLIND${coverage.measurable === 0 ? ": the clock runs and sees nothing" : ""}${coverage.blind.length ? ` on: ${coverage.blind.join(", ")}` : ""}` : ""}.` +
+        tickSentence(coverage.tick),
     };
   }
 

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