agent-coord-mcp 0.26.23 → 0.26.24

package/src/tools/stall.ts

@@ -15,7 +15,8 @@
  * from "nothing ran". A check that only speaks when it fires cannot be told from
  * a broken one.
  */
-import { isLocallyProbeable } from "../transports/index.js";
+import { activeTransport, isLocallyProbeable } from "../transports/index.js";
+import { readFleetTick, tickByAgent, tickVerdict, type FleetTick, type SeatTick } from "./tick.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import path from "node:path";
@@ -24,7 +25,7 @@ import { parseWorkDoc, workstreamsV1RowsOf, workstreamsExtensionsOf, isMalformed
 import { ROOT, AGENTS_FILE, readJson } from "../store.js";
 import { classifyBoardRef, refInCell, rowKindOf, cellKindOf } from "./board-ref.js";
 import { loadLiveTransports } from "./registry.js";
-import { verdictsFor, shaAgrees, verdictShasIn } from "../gated-head.js";
+import { verdictsFor, shaAgrees, verdictShasIn, verdictBoundTo } from "../gated-head.js";
 import { closingsIn, ACCEPTED_FORMS, type Closing } from "../closing-line.js";
 
 const BOARD_DOC = "docs/WORKSTREAMS.md";
@@ -142,6 +143,8 @@ export type StallHit = StallHitBody & { audience: HitAudience };
 export type StallHitBody =
   | { kind: "no-heartbeat"; agentId: string; stream: string; minutes: number }
   | { kind: "no-vcs-activity"; agentId: string; branch: string; minutes: number }
+  /** ⟨q-1c95f7d4⟩ Task 5 — an EXTERNAL observer says the seat is waiting on a person. Not inferred from the branch, and not a verdict about the lane. */
+  | { kind: "seat-blocked"; agentId: string; stream: string; source: string; why: string }
   /**
    * ⟨q-7b2f6c04⟩ — THE CLAIM AXIS: a lane claimed (its row entered in-flight,
    * read from the board's git history) whose branch has nothing on origin —
@@ -262,7 +265,28 @@ export type RepoArtefacts = {
    */
   recentMerges?: RecentMerge[] | null;
 };
-export type RecentMerge = { n: number; headRefOid: string; mergedAt: string; comments: { body: string }[] };
+export type RecentMerge = { n: number; headRefOid: string; mergedAt: string; comments: { body: string }[]; files?: string[] };
+
+/*
+ * ⛔ AN EXPRESS-BY-DESIGN MERGE WITH NO VERDICT IS NOT A DEFECT — ruled by the
+ * coordinator 2026-09-15 after this predicate reported `#966` as a stall. `#966` is
+ * ONE FILE, `+3/-3`, on `docs/WORKSTREAMS.md`, and David's standing rule is that ANY
+ * `.md` change goes direct to main: no PR, no branch, no CI. It legitimately required
+ * no verdict, so reporting it trained the room to ignore the check.
+ *
+ * ⭐ THE EXEMPTION IS MEASURED FROM THE MERGE ITSELF, NOT FROM A LABEL SOMEBODY HAS TO
+ * REMEMBER TO SET. A docs-only file set is a fact `gh` already returns; a lane marker
+ * is a convention, and this row exists because a convention with zero adoption silently
+ * broke the instrument that depended on it.
+ *
+ * ⚠ AND IT COVERS ONLY THE DERIVABLE HALF, WHICH IS SAID RATHER THAN IMPLIED: a SMALL
+ * CODE PR merged express is also exempt by policy and is NOT visible in the file set.
+ * That needs a real lane input from the caller — `expressPrs` below — which nothing
+ * populates yet. So: docs-only is closed here; express-code remains open, and a caller
+ * that knows the lane can pass it without touching this file.
+ */
+export const isDocsOnlyMerge = (files: string[] | undefined): boolean =>
+  Array.isArray(files) && files.length > 0 && files.every((f) => /\.mdx?$/i.test(String(f)));
 const NET_TIMEOUT_MS = 15_000;
 export const realArtefacts = (repo: string): RepoArtefacts => {
   let openPrs: OpenPrFact[] | null = null;
@@ -283,11 +307,12 @@ export const realArtefacts = (repo: string): RepoArtefacts => {
   } catch { /* landedness falls back to patch ids; said so by the caller */ }
   let recentMerges: RecentMerge[] | null = null;
   try {
-    const out = execFileSync("gh", ["pr", "list", "--state", "merged", "--limit", "50", "--json", "number,headRefOid,mergedAt,comments"], {
+    const out = execFileSync("gh", ["pr", "list", "--state", "merged", "--limit", "50", "--json", "number,headRefOid,mergedAt,comments,files"], {
       cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: NET_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
     });
-    recentMerges = (JSON.parse(out) as { number: number; headRefOid: string; mergedAt: string; comments?: { body?: string }[] }[]).map((p) => ({
+    recentMerges = (JSON.parse(out) as { number: number; headRefOid: string; mergedAt: string; comments?: { body?: string }[]; files?: { path?: string }[] }[]).map((p) => ({
       n: p.number, headRefOid: p.headRefOid, mergedAt: p.mergedAt, comments: (p.comments ?? []).map((c) => ({ body: String(c.body ?? "") })),
+      files: (p.files ?? []).map((f) => String(f.path ?? "")).filter(Boolean),
     }));
   } catch { /* said by the caller */ }
   let remoteHeads: { name: string; sha: string }[] | null = null;
@@ -344,7 +369,7 @@ export const CONVENTION_WINDOW_MS = 3 * 24 * 60 * 60 * 1000;
  */
 export const CONVENTION_E_ADOPTED_MS = Date.parse("2026-09-14T13:28:00Z");
 // The verdict grammar lives with the gate predicate now (⟨q-5a93c2d7⟩); re-exported so nothing that reached it here breaks.
-export { VERDICT_COMMENT, verdictShasIn } from "../gated-head.js";
+export { VERDICT_COMMENT, verdictShasIn, verdictClaimsIn, verdictBoundTo } from "../gated-head.js";
 /** Items named ON A GO LINE of a `go` record — position, not mention. */
 export function routedItemsIn(logText: string): { itemId: string; by: string; ts: number }[] {
   const out: { itemId: string; by: string; ts: number }[] = [];
@@ -467,6 +492,8 @@ export function mergeWindowChecks(input: { logText: string; writes: RecordWrite[
 
 export function conventionChecks(input: {
   recentMerges: RecentMerge[] | null | undefined;
+  /** PRs the caller knows merged express. Nothing populates this yet — see isDocsOnlyMerge. */
+  expressPrs?: number[];
   routingLogText: string;
   queueText: string | null;
   boardRows: WorkstreamsV1Row[];
@@ -475,7 +502,7 @@ export function conventionChecks(input: {
 }): {
   hits: StallHit[];
   unmeasurable: { agentId: string; value: string; why: string }[];
-  merges: { pr: number; head: string; minutes: number; verdictAtHead: boolean; inWindow: boolean; beforeAdoption: boolean }[] | null;
+  merges: { pr: number; head: string; minutes: number; verdictAtHead: boolean; inWindow: boolean; beforeAdoption: boolean; exempt?: string }[] | null;
   routed: { itemId: string; by: string; minutes: number; open: boolean | null; onBoard: boolean; inWindow: boolean }[];
   closings: (Closing & { inWindow: boolean })[];
 } {
@@ -483,6 +510,7 @@ export function conventionChecks(input: {
   const hits: StallHitBody[] = [];
   const unmeasurable: { agentId: string; value: string; why: string }[] = [];
   let merges: ReturnType<typeof conventionChecks>["merges"] = null;
+  const expressPrs = new Set(input.expressPrs ?? []);
   if (input.recentMerges === null || input.recentMerges === undefined) {
     unmeasurable.push({ agentId: "-", value: "gh pr list --state merged (with comments)", why: "recent merges could not be read from gh — convention (e), verdicts on the PR, is UNMEASURED, which is not the same as kept" });
   } else {
@@ -492,12 +520,25 @@ export function conventionChecks(input: {
       const minutes = Math.max(0, Math.round((input.now - mergedMs) / 60000));
       const inWindow = input.now - mergedMs <= windowMs;
       const beforeAdoption = mergedMs < CONVENTION_E_ADOPTED_MS;
-      const verdictAtHead = verdictShasIn(m.comments).some((v) => shaAgrees(v.sha, m.headRefOid));
-      merges.push({ pr: m.n, head: m.headRefOid, minutes, verdictAtHead, inWindow, beforeAdoption });
-      if (inWindow && !beforeAdoption && !verdictAtHead) {
+      // ⛔ KEYED ON THE CLAIM, NOT ON A HEADER PHRASE. This used to test `verdictShasIn`,
+      // i.e. #313's `QA GATE — **PASS** @ sha` wording, which had ZERO adoption: on the 9
+      // merges of 2026-09-15 it matched 0 lines while all 9 carried a verdict, so this hit
+      // fired 9 times on 9 correct merges. `verdictBoundTo` asks the binding question
+      // instead — a disposition, on one line, at a sha equal to the head that merged — and
+      // accepts the split halves (#964's CONTENT PASS and READINESS RELEASED were two
+      // separate comments).
+      const bound = verdictBoundTo(m.comments, m.headRefOid);
+      const verdictAtHead = bound.bound;
+      // ⛔ EXEMPT BEFORE REPORTING, NEVER AFTER. A docs-only merge (or one the caller
+      // names as express) owed no verdict, so it is not a hit — it is not a defect
+      // whose report we suppress. `exempt` is carried on the merge row so a reader can
+      // see the population and why a member left it.
+      const exemptWhy = isDocsOnlyMerge(m.files) ? "docs-only" : expressPrs.has(m.n) ? "express lane (caller-supplied)" : null;
+      merges.push({ pr: m.n, head: m.headRefOid, minutes, verdictAtHead, inWindow, beforeAdoption, ...(exemptWhy ? { exempt: exemptWhy } : {}) });
+      if (inWindow && !beforeAdoption && !verdictAtHead && !exemptWhy) {
         hits.push({
           kind: "unverdicted-merge", pr: m.n, head: m.headRefOid, mergedAt: m.mergedAt, minutes,
-          why: `#${m.n} merged at ${m.headRefOid.slice(0, 7)} with no verdict comment bound to that head on the PR (${m.comments.length} comment(s), none a typed \`QA GATE — **PASS|FAIL** @ sha\` line for it). Convention (e): the verdict lives on the PR, not only on the bus.`,
+          why: `#${m.n} merged at ${m.headRefOid.slice(0, 7)} with no verdict comment bound to that head on the PR — ${bound.why} (${m.comments.length} comment(s)). Convention (e): the verdict lives on the PR, not only on the bus. ⚠ This predicate does NOT know about the express lane, so an express merge (no QA verdict by design) still reports here — see the kit row on #966.`,
         });
       }
     }
@@ -1221,6 +1262,8 @@ export async function stallCheckTool(
   artefacts: (repo: string) => RepoArtefacts = realArtefacts,
   readRooms: () => string = readAllRoomLogs,
   readInboxes: () => string = readAllInboxLogs,
+  /** ⟨q-1c95f7d4⟩ the transport the external tick is read through; injected by tests. */
+  tickTransport: Parameters<typeof readFleetTick>[1] = activeTransport(),
 ) {
   const repo = args.repo ?? process.cwd();
   const limit = (args.stallMinutes ?? 30) * 60 * 1000;
@@ -1230,6 +1273,11 @@ export async function stallCheckTool(
   if (!existsSync(board)) return { ok: false as const, error: `no ${BOARD_DOC} under '${repo}'` };
 
   const liveTransports = await loadLiveTransports();
+  // ⟨q-1c95f7d4⟩ Task 5 — the EXTERNAL tick, read once per run for the whole fleet. On a
+  // fleet with no herdr seat this asks nothing and answers "measured NOTHING", which is
+  // what keeps a blind axis from reading as a calm one.
+  const fleetTick: FleetTick = await readFleetTick(liveTransports.values(), tickTransport);
+  const tickOf = tickByAgent(fleetTick);
   const boardText = readFileSync(board, "utf8");
   const boardDoc = parseWorkDoc(boardText);
   const rows = workstreamsV1RowsOf(boardDoc);
@@ -1338,7 +1386,7 @@ export async function stallCheckTool(
    * axes is how all three stayed hidden; every scored row now says which
    * predicate reached a verdict about it, or that none could.
    */
-  type Axis = "vcs" | "review" | "claim" | "landed";
+  type Axis = "vcs" | "review" | "claim" | "landed" | "tick";
   const axes: { agentId: string; stream: string; axis: Axis | null; measurable: boolean; why?: string }[] = [];
   const onAxis = (agentId: string, row: { stream: string }, axis: Axis) => { measured.add(agentId); axes.push({ agentId, stream: row.stream.slice(0, 60), axis, measurable: true }); };
   const offAxis = (agentId: string, row: { stream: string }, why: string) => axes.push({ agentId, stream: row.stream.slice(0, 60), axis: null, measurable: false, why });
@@ -1375,6 +1423,21 @@ export async function stallCheckTool(
       measured.add(agentId);
       continue;
     }
+    // ⟨q-1c95f7d4⟩ 5.2 — THE TICK IS APPLIED FIRST AND SUPPRESSES NOTHING. It may add a
+    // hit and it may credit coverage; every branch and heartbeat predicate below still
+    // runs and still reaches its own verdict, because "the seat is moving" and "the work
+    // is moving" are different questions and only one of them is answered here.
+    const tickSeat: SeatTick | undefined = tickOf.get(agentId);
+    const tick = tickVerdict(tickSeat);
+    if (tick && tickSeat) {
+      if (tick.measured) {
+        onAxis(agentId, row, "tick");
+        if (tick.hit && tickSeat.readable) hits.push({ kind: "seat-blocked", agentId, stream: row.stream.slice(0, 60), source: tickSeat.source, why: tick.why });
+      } else {
+        // 5.3 — A HERDR SEAT WHOSE SIGNAL CANNOT BE READ IS UNMEASURABLE, NEVER HEALTHY.
+        unmeasurable.push({ agentId, value: tickSeat.transport, why: `external tick unreadable: ${tick.why}` });
+      }
+    }
     const entry = reg[agentId];
     if (!entry) {
       // NOT SKIPPED IN SILENCE. An owner with no registry entry has no
@@ -1670,6 +1733,11 @@ export async function stallCheckTool(
     notWatched,
     // ⟨q-7b2f6c04⟩ — per-row axis, beside the one number.
     axes,
+    // ⟨q-1c95f7d4⟩ Task 5 — ONE ENTRY PER SEAT WITH AN EXTERNAL OBSERVER, and nothing that
+    // grows with the fleet's branches or history. Measured on this fleet the day it was
+    // added: 0 seats carry a herdr marker, so this key is 121 bytes of an answer whose
+    // other keys are 76 KB (`stranded.pushedBranches` alone is 35.7 KB).
+    tick: fleetTick,
     stranded: { openPrs: stranded.openPrs, pushedBranches: stranded.pushedBranches, unmeasurable: stranded.unmeasurable },
     conventions: { merges: conventions.merges, routed: conventions.routed, closings: conventions.closings, unmeasurable: conventions.unmeasurable },
     mergeWindows: { windows: mergeWindows.windows, floor: new Date(MERGE_WINDOW_ADOPTED_MS).toISOString(), unmeasurable: mergeWindows.unmeasurable },

package/src/tools/tick.ts

@@ -0,0 +1,117 @@
+/**
+ * ⟨q-1c95f7d4⟩ PHASE 5.4 TASK 5 — THE EXTERNAL TICK, OVER THE FLEET.
+ *
+ * `stall_check` infers. Its liveness axis is pid-existence (and for a local `tmux-push`
+ * seat nothing writes heartbeats at all), its activity axis is VCS commits, and between
+ * them a seat that is THINKING and a seat that is WEDGED are the same reading. herdr
+ * observes the pane from outside the process and answers `idle | working | blocked`, which
+ * is a signal about the SEAT rather than about its branch.
+ *
+ * ⛔ EVIDENCE, NEVER A VERDICT (5.2). Nothing here decides a lane's state: the board says
+ * what work exists, the existing axes say whether it moved, and the tick says whether the
+ * seat is moving. A `working` tick does NOT cancel a stalled branch — a seat can be busy on
+ * the wrong thing — and this module therefore never removes a hit and never marks a row
+ * healthy. It adds evidence and it credits COVERAGE, which is the one thing a real
+ * observation is allowed to do.
+ *
+ * ⛔ A SEAT WITH NO TICK SOURCE PRODUCES NO ENTRY, AND THAT IS THE POINT (5.3). tmux seats
+ * are not given an invented tick: they keep exactly the unmeasurable story they had. A
+ * HERDR seat whose signal cannot be read produces an entry that says so, so `0 of N
+ * readable` reads BLIND and never CALM.
+ */
+import type { Transport, TransportMarker, TickState } from "../transports/types.js";
+import { activeTransport } from "../transports/index.js";
+
+export type SeatTick =
+  | { agentId: string; transport: string; readable: true; state: TickState; source: string }
+  | { agentId: string; transport: string; readable: false; why: string };
+
+export type FleetTick = {
+  /** One entry per seat whose transport HAS an external observer. Never a tmux seat. */
+  seats: SeatTick[];
+  /** Seats whose transport has no tick source at all — named, never silently skipped. */
+  withoutSource: string[];
+  readable: number;
+  states: Partial<Record<TickState, number>>;
+  /** Said in the answer itself: a fleet with a tick source and nothing readable is BLIND. */
+  note: string;
+};
+
+export const NO_SOURCE = "this seat's transport has no external observer to ask — its coverage is unchanged by the tick";
+
+/**
+ * Read the tick for every live marker. `transport` is injected by tests; in the server it
+ * is whatever the configured transport resolved to, so a fleet running tmux asks nothing
+ * and gets an empty, explicitly-blind answer rather than a fabricated one.
+ */
+export async function readFleetTick(
+  markers: Iterable<TransportMarker>,
+  transport: Transport | null | undefined = activeTransport(),
+): Promise<FleetTick> {
+  const seats: SeatTick[] = [];
+  const withoutSource: string[] = [];
+  const states: Partial<Record<TickState, number>> = {};
+  for (const marker of markers) {
+    // The ACTIVE transport is the only thing that can answer, and only for its own kind:
+    // a tmux-push server holding a herdr marker (the 3.4 disagreement state) must not
+    // claim a reading it cannot take.
+    if (!transport || typeof transport.readTick !== "function" || marker.transport !== transport.kind) {
+      withoutSource.push(marker.agentId);
+      continue;
+    }
+    let reading;
+    try {
+      reading = await transport.readTick(marker);
+    } catch (e) {
+      reading = { readable: false as const, why: `the transport threw while reading the tick: ${(e as Error).message}` };
+    }
+    if (reading.readable) {
+      seats.push({ agentId: marker.agentId, transport: marker.transport, readable: true, state: reading.state, source: reading.source });
+      states[reading.state] = (states[reading.state] ?? 0) + 1;
+    } else {
+      seats.push({ agentId: marker.agentId, transport: marker.transport, readable: false, why: reading.why });
+    }
+  }
+  const readable = seats.filter((s) => s.readable).length;
+  return {
+    seats,
+    withoutSource,
+    readable,
+    states,
+    note:
+      seats.length === 0
+        ? `no seat on this bus has an external tick source (${withoutSource.length} seat(s) on a transport that cannot be asked) — the tick measured NOTHING, which is not the same as a calm fleet`
+        : readable === 0
+          ? `${seats.length} seat(s) have a tick source and NONE answered — this fleet is BLIND on the tick axis, not quiet`
+          : `${readable} of ${seats.length} seat(s) with a tick source answered`,
+  };
+}
+
+/** Index by agentId for the per-row lookup in `stall_check`. */
+export const tickByAgent = (tick: FleetTick): Map<string, SeatTick> => new Map(tick.seats.map((s) => [s.agentId, s]));
+
+/**
+ * ⟨q-1c95f7d4⟩ 5.2 — WHAT A READING MEANS FOR A SCORED LANE, as one function so the rule
+ * is testable without a board, a repo or a registry.
+ *
+ * `blocked` is the reading this task was filed for: herdr's blocked means the seat is
+ * WAITING ON A PERSON, and an in-flight lane whose seat waits on a person while the fleet
+ * is away is unattended work that no VCS or heartbeat axis can see. It is reported as a
+ * hit. `working` and `idle` are coverage and nothing else — explicitly NOT a clean bill,
+ * because the branch axes answer a different question and keep their own verdicts.
+ */
+export function tickVerdict(seat: SeatTick | undefined): { measured: boolean; hit: boolean; why: string } | null {
+  if (!seat) return null;
+  if (!seat.readable) return { measured: false, hit: false, why: seat.why };
+  if (seat.state === "blocked")
+    return {
+      measured: true,
+      hit: true,
+      why: `${seat.source} reports the seat BLOCKED — waiting on a person, which no branch or heartbeat axis can see. Evidence about the SEAT, not a verdict about the lane: the row's own axes still say whether the work moved.`,
+    };
+  return {
+    measured: true,
+    hit: false,
+    why: `${seat.source} reports the seat ${seat.state} — coverage, not a clean bill: a seat can be busy on the wrong thing, so the branch axes keep their own verdicts.`,
+  };
+}

package/src/transports/herdr.ts

@@ -34,8 +34,8 @@
  *     same reason (identical evidence for a typo and a default).
  */
 import { spawnSync } from "node:child_process";
-import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker } from "./types.js";
-import { HERDR, targetOf } from "./types.js";
+import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
+import { HERDR, TICK_READS_AS, TICK_STORED_AS, targetOf } from "./types.js";
 
 export type HerdrError = { code: string; message: string };
 export type HerdrResult = {
@@ -285,6 +285,80 @@ export class HerdrTransport implements Transport {
     };
   }
 
+  /**
+   * ⟨q-1c95f7d4⟩ 5.1 — THE EXTERNAL TICK, CONSUMED. herdr's own `agent_status` for the
+   * pane, which is the signal this fleet has never had: our liveness is pid-existence and
+   * our activity is VCS commits, so a THINKING lane and a WEDGED lane are identical to us.
+   *
+   * ⛔ `unknown` AND `done` ARE NOT SEAT STATES AND MUST NOT READ AS CALM. `unknown` is
+   * herdr saying it has no agent there (the shape a plain shell pane returns, measured);
+   * `done` is a finished session, not a moving seat. Both come back UNREADABLE, so the
+   * caller counts them as unmeasured rather than crediting coverage — the exact inversion
+   * (blind read as quiet) that `stall_check` shipped and this task exists to end.
+   */
+  async readTick(marker: TransportMarker): Promise<TickReading> {
+    if (marker.transport !== HERDR) return { readable: false, why: `transport "${marker.transport}" has no external tick — only a herdr marker does` };
+    const target = targetOf(marker);
+    if (!target) return { readable: false, why: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { readable: false, why: avail.reason };
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) {
+      if (got.error?.code === "pane_not_found") return { readable: false, why: `herdr reports pane ${target} not found — a gone pane has no tick (and probe calls it dead)` };
+      return { readable: false, why: `herdr could not describe pane ${target}: ${got.error?.message ?? got.stderr}` };
+    }
+    const status = String(paneOf(got)?.agent_status ?? "unknown");
+    const state = TICK_READS_AS[status];
+    if (state) return { readable: true, state, source: `herdr pane ${target}` };
+    return { readable: false, why: `herdr reports agent_status "${status}" for pane ${target} — no agent state is published there, which is a MISSING signal, not a calm seat` };
+  }
+
+  /**
+   * ⟨q-1c95f7d4⟩ Task 1's open question — PUBLISH, and it needs a receipt it does not get.
+   *
+   * MEASURED 2026-09-15 in a workspace of my own: `herdr pane report-agent <pane> --source
+   * coord-mcp --agent <label> --state blocked` prints NOTHING and exits 0, and the pane
+   * then reads `"agent":"<label>","agent_status":"blocked"` where a second earlier it read
+   * `unknown` with no agent field. ⛔ A WRITE WITH NO OUTPUT IS A WRITE WITH NO RECEIPT:
+   * exit 0 here says the CLI parsed the arguments, not that the pane carries the state, and
+   * a second `report-agent` overwrites the first with the same silence. So this method does
+   * not trust the exit code — it READS THE PANE BACK and reports `ok` only when the pane
+   * carries both the agent label we published and the state we published. An unverifiable
+   * write is returned as an error naming what the pane actually says.
+   *
+   * ⚠ WHAT A WRONG PUBLISH COSTS, stated because the write is silent and destructive:
+   * herdr keeps ONE agent state per pane, so publishing to a pane this bus does not own
+   * overwrites whatever that pane's real agent last reported, with no history and no
+   * notification to the owner — a fleet watching herdr would then read our fiction as the
+   * seat's own signal. Hence the marker gate above (`transport !== HERDR` refuses): we
+   * publish only to panes recorded as herdr seats of this bus, never to a pane id passed in
+   * from anywhere else.
+   */
+  async publishTick(marker: TransportMarker, state: TickState, opts: { message?: string; source?: string } = {}): Promise<{ ok: boolean; error?: string; verified?: boolean }> {
+    if (marker.transport !== HERDR) return { ok: false, error: `refusing to publish state for a "${marker.transport}" seat — herdr keeps one agent state per pane and a publish to a pane this bus does not own would silently overwrite its owner's signal` };
+    const target = targetOf(marker);
+    if (!target) return { ok: false, error: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { ok: false, error: avail.reason };
+    const source = opts.source ?? "coord-mcp";
+    const args = ["pane", "report-agent", target, "--source", source, "--agent", marker.agentId, "--state", state];
+    if (opts.message) args.push("--message", opts.message);
+    const wrote = this.#run(args);
+    if (!wrote.ok) return { ok: false, error: `herdr refused the report: ${wrote.error?.message ?? wrote.stderr}` };
+    // THE RECEIPT IS THE READ-BACK, never the exit code.
+    const back = this.#run(["pane", "get", target]);
+    if (!back.ok) return { ok: false, verified: false, error: `published, but the pane could not be read back to verify it: ${back.error?.message ?? back.stderr}` };
+    const pane = paneOf(back);
+    const gotAgent = String(pane?.agent ?? "");
+    const gotState = String(pane?.agent_status ?? "");
+    // VERIFIED AGAINST WHAT herdr STORES, not against what we sent: a published `idle`
+    // comes back as `done` (TICK_STORED_AS, measured). Comparing to the sent word would
+    // call every idle publish a failure; comparing to the stored word is the receipt.
+    const expected = TICK_STORED_AS[state];
+    if (gotAgent === marker.agentId && gotState === expected) return { ok: true, verified: true };
+    return { ok: false, verified: false, error: `published --agent ${marker.agentId} --state ${state} (herdr stores that as "${expected}"), but pane ${target} reads agent "${gotAgent || "(none)"}" state "${gotState || "(none)"}" — the write did not land as published` };
+  }
+
   /**
    * No pusher to kill. A herdr marker whose pane is gone is reaped (the caller deletes
    * the marker); an unknown answer is unprobeable; a live pane is left alone.

package/src/transports/types.ts

@@ -154,6 +154,53 @@ export type Liveness =
   | { state: "dead"; reason: string }
   | { state: "unknown"; reason: string };
 
+/**
+ * ⟨q-1c95f7d4⟩ Phase 5.4 Task 5 — THE EXTERNAL TICK'S VOCABULARY, TAKEN FROM THE TOOL THAT
+ * OWNS IT. Measured 2026-09-15 in a workspace of my own: `herdr pane report-agent --help`
+ * enumerates exactly `idle, working, blocked, unknown`, and a pane carries the state an
+ * external source published (`"agent":"<label>","agent_status":"blocked"` on a pane that
+ * read `unknown` a second earlier). So these four are herdr's own set, not ours.
+ *
+ * ⛔ `unknown` IS THE ABSENCE OF A SIGNAL, NOT A STATE OF THE SEAT. A tick that reads
+ * `unknown` is UNREADABLE — reported as such and counted as unmeasured — because the whole
+ * defect this task answers is a fleet that reads CALM when it is BLIND (Task 5.3).
+ */
+export const TICK_STATES = ["idle", "working", "blocked"] as const;
+export type TickState = (typeof TICK_STATES)[number];
+
+/**
+ * ⛔⛆ THE WRITE VOCABULARY AND THE READ VOCABULARY ARE NOT THE SAME, AND ONLY A READ-BACK
+ * FINDS IT. Measured 2026-09-16 on a fresh pane of my own, six writes and three repeats:
+ *
+ *   published --state working  → agent_status "working"
+ *   published --state blocked  → agent_status "blocked"
+ *   published --state idle     → agent_status "done"      ⬅ 3 of 3, with and without --seq
+ *   published --state unknown  → agent_status "unknown"
+ *
+ * herdr ACCEPTS `idle` (its own `--help` lists it) and STORES `done`. Nothing in the CLI
+ * says so: the write prints nothing and exits 0 either way. This is exactly what the
+ * receipt exists to catch, and it was caught by the read-back failing, not by reasoning.
+ *
+ * For the tick's purpose the two mean the same thing — a seat that is not working — so a
+ * `done` READS as `idle`, and a publish of `idle` is verified against `done`. The
+ * translation is named here rather than hidden in a comparison, so a herdr release that
+ * changes it fails a test instead of quietly inverting a verdict.
+ *
+ * ⚠ THE TWO DIRECTIONS ARE NOT THE SAME SET, AND THE `done` ENTRY IS NOT DEAD CODE — qa
+ * measured the asymmetry from the other side on herdr 0.9.0: `report-agent --state done`
+ * is REFUSED ("expected idle, working, blocked, or unknown"), so nothing we publish can
+ * produce it. It is still REACHABLE ON READ, which is the side `TICK_READS_AS` serves:
+ * `agent_status` is what a pane REPORTS, and herdr's own `agent wait --until` enumerates
+ * `idle, working, blocked, done, unknown`. A herdr-managed Claude session that finishes
+ * hands us `done` without anyone publishing it. So: refused on write, reachable on read,
+ * measured in both directions — do not delete this entry as unreachable.
+ */
+export const TICK_STORED_AS: Readonly<Record<TickState, string>> = Object.freeze({ idle: "done", working: "working", blocked: "blocked" });
+export const TICK_READS_AS: Readonly<Record<string, TickState>> = Object.freeze({ idle: "idle", done: "idle", working: "working", blocked: "blocked" });
+export type TickReading =
+  | { readable: true; state: TickState; source: string }
+  | { readable: false; why: string };
+
 /** Keystroke-shaped commands a transport must deliver to an interactive pane. */
 export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
 export type ControlCommand = (typeof CONTROL_COMMANDS)[number];
@@ -198,4 +245,23 @@ export interface Transport {
   sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }>;
 
   reapWedged(markers: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }>;
+
+  /**
+   * ⟨q-1c95f7d4⟩ 5.1 — OPTIONAL, AND ITS ABSENCE IS THE HONEST ANSWER FOR tmux.
+   *
+   * A transport implements `readTick` only when something OUTSIDE this process observes
+   * the seat and can be asked. tmux cannot: a pane is a terminal, and "a pid exists" is
+   * what `probe` already says. Declaring the method optional is what keeps `stall_check`
+   * from inventing a tick for a tmux seat and reading a fabricated calm — those seats keep
+   * the unmeasurable story they had (5.3).
+   */
+  readTick?(marker: TransportMarker): Promise<TickReading>;
+
+  /**
+   * ⟨q-1c95f7d4⟩ Task 1's open question, answered by measurement: THE PIPE RUNS BOTH WAYS.
+   * `coord-mcp` knows what herdr cannot infer — which seat holds which lane, whether a
+   * DONE: awaits a verdict, whether a seat is parked on a David decision — so a transport
+   * that can PUBLISH state to its external observer exposes it here.
+   */
+  publishTick?(marker: TransportMarker, state: TickState, opts?: { message?: string; source?: string }): Promise<{ ok: boolean; error?: string }>;
 }