agent-coord-mcp 0.26.23 → 0.26.25

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/tools/transport.ts

@@ -1,4 +1,4 @@
-import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+import { loadLiveTransports, isMarkerLive, isPidAlive, markerHoldsLiveProcess } from "./registry.js";
 import {
   TMUX_PUSH,
   registerTmuxHost,
@@ -685,7 +685,8 @@ export async function attachAgentTool(args: {
       agentId: args.agentId,
       transport: HERDR,
       target: marker.target,
-      pid: 0,
+      pid: marker.pid,
+      pidWhy: marker.pidWhy,
       rooms: marker.rooms,
       note: "herdr socket transport: no pusher process — delivery is made in-process by this server through herdr's socket API; liveness is herdr's own pane status",
     };
@@ -711,10 +712,10 @@ export async function attachAgentTool(args: {
 
   // If something's already attached, refuse rather than spawn a second pusher.
   const existing = await readJson<TransportMarker | null>(transportFile(args.agentId), null);
-  if (existing && isPidAlive(existing.pid)) {
+  if (markerHoldsLiveProcess(existing)) {
     return {
       ok: false,
-      error: `agent '${args.agentId}' already has a live ${existing.transport} attached (pid ${existing.pid}). Call detach_agent first.`,
+      error: `agent '${args.agentId}' already has a live ${existing!.transport} attached (pid ${existing!.pid}). Call detach_agent first.`,
       existing,
     };
   }