agent-coord-mcp 0.26.22 → 0.26.24

package/src/gated-head.ts

@@ -207,13 +207,189 @@ 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.
  */
 export const VERDICT_COMMENT = /^(?:QA GATE|\*\*GATE|GATE)\b[^\n]*?\b(PASS|FAIL)\b(?:\s*\([^)\n]*\))?[^\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.
+ */
+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/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/event-kinds.ts

@@ -29,7 +29,8 @@ export type SubKind = keyof typeof EVENT_KINDS;
  * FIRE, whatever the emitter list and the scan clock say.
  */
 export type KindProbe = { diff: string; after?: { done?: string; phases?: Record<string, string> } };
-export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
+/** `refs`: ⟨q-cbace757⟩ — a closure cited by N PRs carries all N, each checked against the record on its own; `ref` stays the joined form for the event key. */
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string; refs?: string[] };
 
 /*
  * THE KIND REGISTRY IS THE SINGLE SOURCE, AND THAT IS TASK 9.2.

package/src/tools/events.ts

@@ -177,11 +177,18 @@ export const eventKey = (kind: SubKind, target: string, ref: string): string =>
  */
 export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true } | { ok: false; error: string } {
   if (!ev.ref) return { ok: false, error: `event for ${ev.kind} ${ev.target} carries no ref — nothing ties it to a record entry` };
-  if (!String(recordText).includes(ev.ref))
+  // ⟨q-cbace757⟩ — a multi-PR closer is N citations, checked ONE BY ONE. The
+  // joined string ("a#1, a#2, a#3") is how the event is keyed, not how the record
+  // is read: a DONE line citing the same three PRs in another arrangement carries
+  // every ref and none of the joined form. The guard stays exactly as strict per
+  // ref — a citation absent from the record still refuses, and is named.
+  const refs = ev.refs?.length ? ev.refs : [ev.ref];
+  const missing = refs.filter((r) => !String(recordText).includes(r));
+  if (missing.length)
     return {
       ok: false,
       error:
-        `refusing to emit ${ev.kind} ${ev.target}: its ref ${ev.ref} is NOT in the record. ` +
+        `refusing to emit ${ev.kind} ${ev.target}: ${missing.length === refs.length && refs.length === 1 ? `its ref ${ev.ref}` : `${missing.length} of its ${refs.length} cited ref(s) — ${missing.join(", ")} —`} is NOT in the record. ` +
         `An event that exists without the record change that caused it is a second source of truth — ` +
         `the stream would claim something the authoritative document does not.`,
     };

package/src/tools/herdr-delivery.ts

@@ -0,0 +1,87 @@
+/**
+ * IN-PROCESS DELIVERY FOR HERDR SEATS (Phase 5.4 Task 4, box 4.4).
+ *
+ * A tmux seat has a pusher that tails its inbox and the rooms it joined, formats a batch,
+ * types it into the pane and advances the PUSH cursor once the paste is verified submitted
+ * (hooks/tmux-pusher.mjs + hooks/push-cursor.mjs). A herdr seat has no pusher, so the
+ * server does the same at SEND time: the message it just appended is formatted by the very
+ * same formatter the pusher uses (hooks/tier.mjs — one renderer, so the pane sees one
+ * shape on either transport), pushed through the transport, and ONLY on a verified
+ * delivery is the seat's push cursor advanced past it.
+ *
+ * THE CURSOR RULE IS THE PUSHER'S, UNCHANGED (⟨q-7be94b5e⟩): a paste that did not reach the
+ * pane must not mark the message consumed. The push cursor is advanced to the offset the
+ * append produced, and never touched when the transport reports not-delivered — the
+ * message stays where `read_messages` still serves it. The READ cursor is the agent's and
+ * is never written here.
+ *
+ * Simplification stated: the pusher batches routine room traffic into digests on a
+ * debounce; a herdr seat receives each message as it is sent, in the digest FORMAT (the
+ * `[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 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 type { Message } from "./shared.js";
+
+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 };
+let hooks: Promise<{ tier: Tier; cursor: PushCursor }> | undefined;
+function loadHooks(): Promise<{ tier: Tier; cursor: PushCursor }> {
+  hooks ??= (async () => {
+    const base = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "..", "hooks");
+    const tier = (await import(pathToFileURL(path.join(base, "tier.mjs")).href)) as Tier;
+    const cursor = (await import(pathToFileURL(path.join(base, "push-cursor.mjs")).href)) as PushCursor;
+    return { tier, cursor };
+  })();
+  return hooks;
+}
+const safeId = (id: string) => id.replace(/[^A-Za-z0-9._-]/g, "_");
+
+export type HerdrDeliveryOutcome = { agentId: string; delivered: boolean; enters?: number; error?: string; cursorAdvanced: boolean };
+
+/** 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[]> {
+  const t = activeTransport();
+  if (!t || t.kind !== HERDR) return [];
+  let markers: Map<string, TransportMarker>;
+  try { markers = await loadLiveTransports(); } catch { return []; }
+  const out: HerdrDeliveryOutcome[] = [];
+  for (const agentId of recipients) {
+    const marker = markers.get(agentId);
+    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] : []);
+    // 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 };
+    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 });
+  }
+  return out;
+}

package/src/tools/messaging.ts

@@ -84,6 +84,7 @@ import {
   isDecision,
 } from "./shared.js";
 import { isKnownHuman } from "../store.js";
+import { deliverToHerdrSeats } from "./herdr-delivery.js";
 import { verifyCommitCite } from "../commit-cite.js";
 
 // ---------- send_message ----------
@@ -454,6 +455,9 @@ export async function sendMessageTool(args: {
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
+    // Phase 5.4 Task 4 — a herdr-attached recipient has no pusher: deliver now, in-process.
+    const herdr = await deliverToHerdrSeats(msg, [args.to], { kind: "dm" });
+    void herdr;
     // Offline delivery is intentional (the inbox is created on demand), but a
     // typo'd recipient shouldn't vanish silently — surface a warning when the
     // target isn't a known agent so the caller can catch the mistake.
@@ -482,6 +486,10 @@ export async function sendMessageTool(args: {
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
+  // Phase 5.4 Task 4 — herdr-attached members with rooms on receive the post now, in-process.
+  const roomMembers = (await getRooms())[chan]?.members ?? [];
+  const herdrRoom = await deliverToHerdrSeats(msg, roomMembers, { kind: "room", chan });
+  void herdrRoom;
   await maybeCompactRoom(chan);
   const roomWarning = [typedWarning, replyWarning, slashWarning].filter(Boolean).join("; ") || undefined;
   return { ok: true, id: msg.id, target, room: chan, ...(roomWarning ? { warning: roomWarning } : {}) };

package/src/tools/queue-write.ts

@@ -395,7 +395,10 @@ export async function queueWriteTool(args: {
               `item by hand once, or move the queue section last.`,
           );
         }
-        const w0 = writeDoc(repo, QUEUE_DOC, reparsed, original);
+        // `own` names the row this call authored. It is already recorded above, so this
+  // changes nothing today — it is stated so the guarantee survives a refactor that
+  // stops pre-stamping, rather than depending on line 361 staying where it is.
+  const w0 = writeDoc(repo, QUEUE_DOC, reparsed, original, [], [target.id]);
         return {
           ok: true,
           op: args.op,

package/src/tools/record-events.ts

@@ -120,6 +120,48 @@ const norm = (s: string) => String(s).toLowerCase().replace(/[`*_]/g, "").replac
  * against them by the caller (`eventIsDerived`), so a diff that has since been
  * reverted cannot produce an event that outlives the record.
  */
+/**
+ * ⟨q-…⟩ PHASE COMPLETENESS IS THE ABSENCE OF AN UNTICKED BOX, AND IT MUST NOT DEPEND ON WHAT
+ * A BOX IS CALLED.
+ *
+ * ⛔ MEASURED, NOT REASONED — a false "phase 5.4 complete" event was emitted and DELIVERED on
+ * 2026-09-16 at `579db9d`. The detector's box pattern required a label shaped `\d+\.\d+`, so
+ * against the real document it saw **31 of 36** checkboxes, every one of them ticked, and
+ * fired. The three it could not see were `3B.2`, `3B.3` and `3B.4` — labels with a LETTER
+ * inside the number — and `3B.3` is deliberately unticked and not recoverable.
+ *
+ * ⚠ SO THE CAUSE IS THE LABEL PATTERN, NOT THE POSITION OF THE LAST BOX. The event cited
+ * `- [x] 6.4`, the document's final line, which made it look like a last-line rule; the ref is
+ * only what it cites. Any doc whose remaining work carries an unanticipated label reported
+ * itself finished, wherever that work sat.
+ *
+ * ⭐ THE FIX IS A DIFFERENT QUESTION, not a wider regex for the same one: "is any checkbox in
+ * this document unticked" is asked over EVERY markdown checkbox, whatever follows it. A label
+ * shape nobody has invented yet cannot defeat it. The failure direction is deliberate — an
+ * unticked box anywhere blocks the event, so an unrecognised box costs a MISSED completion,
+ * never a FALSE one. This code's own comment already said which way to lean: *"A false
+ * completion is worse than a missing one: it closes a phase nobody finished."*
+ */
+export const ANY_BOX = /^[ \t]*[-*+][ \t]*\[([ xX])\][ \t]*(.*)$/;
+export const TICKED_BOX = /^[ \t]*[-*+][ \t]*\[[xX]\]/;
+
+export type PhaseBox = { ticked: boolean; label: string | null; line: string };
+
+/** Every markdown checkbox in a phase document, in file order, label-agnostic. */
+export function checkboxesIn(text: string): PhaseBox[] {
+  const out: PhaseBox[] = [];
+  for (const raw of String(text).split("\n")) {
+    const m = ANY_BOX.exec(raw);
+    if (!m) continue;
+    const rest = m[2] ?? "";
+    out.push({ ticked: m[1]!.toLowerCase() === "x", label: (/^\*{0,2}([A-Za-z0-9][A-Za-z0-9.]*)\b/.exec(rest) ?? [])[1] ?? null, line: raw.trim() });
+  }
+  return out;
+}
+
+/** The unticked boxes, for a caller that wants to say WHY it did not fire. */
+export const untickedIn = (text: string): PhaseBox[] => checkboxesIn(text).filter((b) => !b.ticked);
+
 export function eventsFromCommittedChange(
   diff: string,
   after: { done?: string; phases?: Record<string, string> } = {},
@@ -257,14 +299,14 @@ export function eventsFromCommittedChange(
   // finished.
   for (const [rel, text] of Object.entries(after.phases ?? {})) {
     if (!isPhaseDoc(rel)) continue;
-    const boxes = [...String(text).matchAll(/^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+[a-z]?)\b/gim)];
-    if (!boxes.length || boxes.some((m) => m[1] !== "x")) continue;
+    const boxes = checkboxesIn(String(text));
+    if (!boxes.length || boxes.some((b) => !b.ticked)) continue;
     // This commit must have ticked a box IN THIS FILE.
-    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => /^\s*-\s*\[x\]\s*\*{0,2}\d+\.\d+/.test(l));
+    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => TICKED_BOX.test(l));
     if (!closedHere) continue;
     const phase = /phase(\d+(?:\.\d+)?)/i.exec(rel)?.[1];
     if (!phase) continue;
-    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]![0].trim(), summary: `phase ${phase} — every task box ticked` });
+    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]!.line, summary: `phase ${phase} — every task box ticked` });
   }
 
   lastUnattributedItems = unattributedItems;

package/src/tools/records.ts

@@ -45,6 +45,7 @@ import { verdictsFor, gatedBy, prVerdictsIn } from "../gated-head.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
+import { prRefsIn } from "./record-events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
 const DONE_DOC = "docs/DONE.md";
@@ -148,8 +149,12 @@ export function writeDoc(
   doc: WorkDoc,
   original: string,
   alreadyWritten: string[] = [],
+  own: readonly string[] = [],
 ): { written: boolean; stamped: string[] } {
-  const { text, stamped } = renderWorkDocForWrite(doc);
+  // `own` = the rows THIS CALL authored. Everything else is stamped only if the
+  // document already speaks the recorded-id grammar — see `stampQueueIds`, which
+  // holds the rule so both writers cannot drift apart on it.
+  const { text, stamped } = renderWorkDocForWrite(doc, { own });
   if (text === original) return { written: false, stamped: [] };
   const p = path.join(repo, rel);
   const current = existsSync(p) ? readFileSync(p, "utf8") : "";
@@ -169,6 +174,53 @@ function prNumber(pr: string): string | null {
   const m = /#(\d+)\b/.exec(String(pr)) ?? /^(\d+)$/.exec(String(pr).trim());
   return m ? (m[1] as string) : null;
 }
+/** ⟨q-cbace757⟩ — EVERY PR number a citation names, in order; a multi-PR closer is N citations. */
+function prNumbersOf(pr: string): string[] {
+  const out: string[] = [];
+  for (const m of String(pr).matchAll(/#(\d+)\b/g)) if (!out.includes(m[1]!)) out.push(m[1]!);
+  if (!out.length) { const one = prNumber(pr); if (one) out.push(one); }
+  return out;
+}
+/*
+ * ⟨q-b7198479⟩ — THE LOOKUP IS NOT BOUNDED BY A WINDOW. `git log -n 400` missed
+ * #245's squash 777 commits back on an 1806-commit main and the verb then
+ * asserted "#245 is not on origin/main" as a fact — a truncated search reported
+ * as an absence, at the verb that writes the delivery record, and worded with a
+ * mechanism (target tip vs merge base) that had nothing to do with it. At the
+ * fleet's speed (~200 record commits a day) 400 is about two days, so it fires
+ * precisely on the oldest rows, the ones closed late.
+ *
+ * Now: `git log --grep` over the WHOLE of the ref, then the SUBJECT is judged
+ * BY IDENTITY, the rule #327's mergeOf and the closing-line grammar already use:
+ * the landing is the commit whose subject ENDS with the forge's `(#N)` marker.
+ * A bare `#N` anywhere is a mention, never a landing — qa measured the first
+ * cut of this (`\(#N\)|#N\b`, newest first) on live origin/main: 149 of 322
+ * squash-merged PRs resolved to their CLOSURE or board commit ("docs(record):
+ * close … by content on #245"), which carry the bare number in the subject and
+ * sit newer than the squash. Among trailing-(#N) subjects the OLDEST wins: a
+ * hand-written "docs: log Task 10 (#164)" copied the marker 36 s after #164's
+ * squash and would otherwise be taken for it. The one PR of 323 on this main
+ * that landed as a merge commit (#108, "Merge pull request #108 from …") is the
+ * second identity form — the forge's own, not a mention — and is the last
+ * resort, consulted only when no trailing form exists. A miss reports what was
+ * searched — every subject on the ref — never a mechanism it did not test.
+ */
+export function landingCommitOf(repo: string, ref: string, n: string): { sha: string | null; searched: number } {
+  const searched = Number(git(repo, ["rev-list", "--count", ref])) || 0;
+  // git's --grep is a basic regex with no `\b`; identity is decided on the SUBJECT below.
+  const out = git(repo, ["log", ref, "--format=%H%x00%s", `--grep=#${n}`]);
+  const trailing = new RegExp(`\\(#${n}\\)\\s*$`);
+  const mergeForm = new RegExp(`^Merge pull request #${n}(?:\\s|$)`);
+  let landing: string | null = null;
+  let merge: string | null = null;
+  for (const line of out.split("\n")) {
+    const [sha, subject = ""] = line.split("\x00");
+    if (!sha) continue;
+    if (trailing.test(subject)) landing = sha; // newest first: the last hit is the OLDEST
+    else if (!merge && mergeForm.test(subject)) merge = sha;
+  }
+  return { sha: landing ?? merge, searched };
+}
 
 /**
  * The `owner/repo` a BARE `#N` in this repo's docs should be read as naming —
@@ -1015,19 +1067,31 @@ export async function landTool(
   const ref = `origin/${base}`;
   let landedIn: string | null = null;
   let reason: string | null = null;
+  // ⟨q-cbace757⟩ — every cited PR must be on the ref, not only the first.
+  const numbers = prNumbersOf(args.pr);
+  const landings: Record<string, string> = {};
+  let searched = 0;
+  const missing: string[] = [];
   try {
-    const subjects = git(repo, ["log", "-n", "400", "--format=%H %s", ref]);
-    const hit = subjects.split("\n").find((l) => new RegExp(`\\(#${n}\\)|#${n}\\b`).test(l));
-    landedIn = hit ? (hit.split(" ")[0] as string) : null;
+    for (const num of numbers) {
+      const found = landingCommitOf(repo, ref, num);
+      searched = found.searched;
+      if (found.sha) landings[num] = found.sha; else missing.push(num);
+    }
+    landedIn = landings[n] ?? null;
   } catch (e) {
     reason = `could not read ${ref} (${String((e as Error).message).split("\n")[0]}) — NOT checked, which is not the same as checked and absent`;
   }
   if (reason) return { ok: false as const, error: reason };
-  if (!landedIn) {
+  if (!landedIn || missing.length) {
     return {
       ok: false as const,
-      error: `#${n} is not on ${ref} — refusing to record it as landed. Compared against the TARGET TIP (${ref}), not a merge base: an item merged after this branch was cut is missing from the base too.`,
+      error:
+        `${missing.map((m) => `#${m}`).join(", ")} not found on ${ref}: none of the ${searched} commit subject(s) on ${ref} carries ` +
+        `${missing.map((m) => `"(#${m})"`).join(" or ")} — refusing to record it as landed. The whole of ${ref} was searched, not a window; ` +
+        `a PR merged under another number or never merged reads the same here — check \`gh pr view\`.`,
       comparedAgainst: ref,
+      searched,
     };
   }
 
@@ -1205,7 +1269,7 @@ export async function landTool(
   try {
   if (args.write) {
     if (queueChanged) {
-      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote);
+      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote, args.queueItemId ? [args.queueItemId] : []);
       if (w.written) wrote.push(QUEUE_DOC);
       // Rows stamped that this call did not ask to touch. `queueItemId` is the
       // one item the caller supplied, so anything else here is a row that
@@ -1259,7 +1323,9 @@ export async function landTool(
   if (args.write && target) {
     const after = readDoc(repo, DONE_DOC);
     const recordText = after?.text ?? "";
-    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(originalText ?? "") };
+    // ⟨q-cbace757⟩ — one event, every cited ref; each checked against the record on its own.
+    const refs = prRefsIn(args.pr);
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: refs.length ? refs.join(", ") : args.pr, summary: summarize(originalText ?? ""), ...(refs.length > 1 ? { refs } : {}) };
     const derived = eventIsDerived(recordText, ev);
     if (!derived.ok) {
       events.refused.push(derived.error);