agent-coord-mcp 0.26.21 → 0.26.22

package/src/commit-cite.ts

@@ -0,0 +1,58 @@
+/**
+ * ⟨q-cc0819dc⟩ — A `done` MAY CITE A COMMIT WHEN THE WORK HAS NO PR BY RULE.
+ *
+ * Docs-direct work (queue curation, canon, board moves) is pushed straight to the shared
+ * branch by policy; the `done` gate demanded a `{kind:'pr'}` cite, so the compliant path did
+ * not exist and the aide downgraded to `fyi` (2026-09-12 15:50). The fix accepts a commit
+ * cite — and only a commit that is REAL: a fabricated sha must not become a citable DONE.
+ *
+ * What "real" means here, stated so the ancestry call below is not mistaken for a merge test:
+ *   is this exact commit object reachable from origin/main in `repo`? A docs-direct push puts
+ *   THE COMMIT ITSELF on the shared branch, so reachability is the right question for it — this
+ *   is not "was this branch's work squashed in", which `--is-ancestor` cannot answer
+ *   (docs/LANDEDNESS.md); a squash-merged PR is cited by its PR, never by its branch sha.
+ *
+ * Full 40-hex only, REFUSED rather than normalised: a prefix is a claim about a sha the
+ * joiners (verdict/landing/closure readers) compare in full; normalising here would write a
+ * sha the sender never saw. No network: one local `git` in `repo`, which the caller passes
+ * because the send path has no repository of its own.
+ */
+import { execFileSync } from "node:child_process";
+
+export const FULL_SHA = /^[0-9a-f]{40}$/;
+export const SHARED_BRANCH_CANDIDATES = ["origin/main", "origin/master"];
+
+export type CommitCiteVerdict =
+  | { ok: true; sha: string; branch: string }
+  | { ok: false; why: string };
+
+function git(repo: string, args: string[]): { status: number; out: string } {
+  try {
+    const out = execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return { status: 0, out: out.trim() };
+  } catch (e) {
+    return { status: Number((e as { status?: number }).status ?? 1), out: "" };
+  }
+}
+
+/** Verify one commit cite against the shared branch of `repo`. */
+export function verifyCommitCite(ref: string, repo: string | undefined): CommitCiteVerdict {
+  const sha = String(ref ?? "").trim();
+  if (!FULL_SHA.test(sha)) {
+    return { ok: false, why: `commit cite '${sha}' is not a full 40-hex sha — refused, not normalised: a prefix is a claim the joiners compare in full` };
+  }
+  if (!repo) {
+    return { ok: false, why: `commit cite ${sha.slice(0, 7)} cannot be verified without \`repo\` — pass the repository whose origin/main carries it (no network is used)` };
+  }
+  if (git(repo, ["rev-parse", "--verify", "--quiet", `${sha}^{commit}`]).status !== 0) {
+    return { ok: false, why: `commit ${sha.slice(0, 7)} does not exist in ${repo} — a sha the repository has never seen cannot be a citable DONE` };
+  }
+  for (const branch of SHARED_BRANCH_CANDIDATES) {
+    if (git(repo, ["rev-parse", "--verify", "--quiet", branch]).status !== 0) continue;
+    // Is the cited commit reachable from the shared branch? (the reachability question,
+    // asked of the commit object itself — see the header for why that is the right one here)
+    if (git(repo, ["merge-base", "--is-ancestor", sha, branch]).status === 0) return { ok: true, sha, branch };
+    return { ok: false, why: `commit ${sha.slice(0, 7)} exists but is not reachable from ${branch} — work that is done is on the shared branch; a commit that is not is not done` };
+  }
+  return { ok: false, why: `${repo} has no origin/main or origin/master to verify commit ${sha.slice(0, 7)} against — fetch the shared branch first` };
+}

package/src/gated-head.ts

@@ -51,7 +51,20 @@ export function shaAgrees(a: string | undefined, b: string | undefined): boolean
   return x.length <= y.length ? y.startsWith(x) : x.startsWith(y);
 }
 
-export type PassVerdict = { head: string; ts: number; from: string; result: string };
+/*
+ * ⟨q-dcbaf544⟩ — A VERDICT NAMES ITS SENDER AND NEVER ITS GATER. The record's
+ * `from` is whoever SENT it; when a gate is routed to a seat whose role cannot
+ * emit `verdict` (repo-owner, console — David's ruling: authority does not
+ * move), a gate-runner SCRIBES it, and the gater then survives only in prose.
+ * A name in prose is a mention; a name in a field is a position — only the
+ * position survives a scanner. So the record carries `gatedBy` (who judged)
+ * and `scribe` (who transcribed), the spelling the three live scribed records
+ * already used, and every reader attributes by `gatedBy ?? from`.
+ */
+export type PassVerdict = { head: string; ts: number; from: string; result: string; channel?: "bus" | "pr"; gatedBy?: string; scribe?: string };
+/** Who JUDGED: the typed gater when scribed, else the sender. Never `from` alone. */
+export const gaterOf = (v: Pick<PassVerdict, "from" | "gatedBy">): string => v.gatedBy ?? v.from;
+const nonEmpty = (x: unknown): string | undefined => (typeof x === "string" && x.trim() ? x : undefined);
 
 /** The PR number a verdict record is about, from its `cites`. */
 function citedPr(cites: unknown): string | null {
@@ -86,49 +99,138 @@ export function verdictsFor(logText: string, pr: string): { verdicts: PassVerdic
     const r = o.record as { type?: string; payload?: Record<string, unknown>; cites?: unknown } | undefined;
     if (!r || r.type !== "verdict") continue;
     if (citedPr(r.cites) !== pr) continue;
+    const gatedBy = nonEmpty(r.payload?.gatedBy);
+    const scribe = nonEmpty(r.payload?.scribe);
     verdicts.push({
       head: String(r.payload?.headRefOid ?? ""),
       ts: Number(o.ts ?? 0),
       from: String(o.from ?? ""),
       result: String(r.payload?.result ?? ""),
+      ...(gatedBy ? { gatedBy } : {}),
+      ...(scribe ? { scribe } : {}),
     });
   }
   return { verdicts, lines: lines.length, unparsed };
 }
 
-export type GateAnswer =
-  | { gated: true; by: PassVerdict }
-  | { gated: false; reason: string; crossed?: { gatedSha: string; at: number }[] };
-
+/*
+ * ⟨q-5a93c2d7⟩ — GATEDNESS IS A PROPERTY OF (HEAD SHA, TYPED VERDICT), NOT OF
+ * CLOCK ORDERING. Measured on the two UNGATED records `land` had written:
+ *
+ *   #309  qa's PASS comment on the PR 16:10:12Z · merged 16:10:16Z · bus record 16:10:19Z
+ *   #310  PR comment 16:20:14Z · merged 16:20:18Z · bus record 16:20:21Z
+ *
+ * The PR carried a clean typed PASS four seconds BEFORE each merge; the bus
+ * record trailed the merge by three; `gatedAt` read only the bus and only
+ * records with ts ≤ mergedAt, and called both merges UNGATED. With one true
+ * (#299) and two false UNGATEDs on the record, the marker had stopped
+ * discriminating — the one-label-two-states failure, on the artefact that
+ * exists to police merges.
+ *
+ * So: a verdict NAMING THE MERGED HEAD is a verdict ABOUT that head whenever
+ * it was written and wherever it was recorded — the bus (any room) or the PR
+ * page (the typed line, #313's grammar; #299's "not a verdict" review does
+ * not match it). `recordedAt > mergedAt` imports a precondition the question
+ * never had. THE COST IS ACCEPTED AND DISCLOSED: #268's own records now read
+ * gated — qa re-issued a PASS bound to the merged head 4m44s after the merge
+ * — and the report says so IN WORDS beside "gated", because a reader who sees
+ * "gated" without "recorded 4m44s after the merge" has been told half a fact.
+ */
+/*
+ * ⟨q-6f4a19c8⟩ — THE EARLIEST MATCH IS USUALLY THE PR COMMENT, AND THE PR
+ * CHANNEL CANNOT NAME A GATER: one GitHub account serves six seats, so a
+ * citation built from it reads "by davidbalzan" for a merge QA gated. Measured
+ * on qa's own land dry run at #316: #310 and #316, both gated by qa, neither
+ * citation said so. The earliest-match rule is CORRECT (it is what stops a late
+ * bus record shadowing a PR comment that preceded the merge) and stays; the
+ * remedy sits beside it — the earliest TIME and the identifiable AUTHOR need
+ * not be the same record. When the earliest match is a PR comment and a bus
+ * verdict names the same head, the citation carries both: the SEAT from the
+ * bus, first seen on the PR at the comment's time. A PR-only verdict still
+ * names the account, and says in words that it is an account, not a seat.
+ */
+export type GateVerdict =
+  | {
+      gated: true;
+      by: PassVerdict;
+      lateByMs: number | null;
+      verified: string;
+      /** `gatedBy ?? from` of the record that can NAME a seat; the PR account only when no channel can. */
+      gater: string;
+      attribution: "seat" | "account";
+      /** The bus record that named the seat when `by` is a PR comment. */
+      seatRecord?: PassVerdict;
+    }
+  | { gated: false; reason: string; crossed?: { gatedSha: string; at: number; channel: string }[] };
+export const fmtLate = (ms: number): string => (ms < 60_000 ? `${Math.round(ms / 1000)}s` : ms < 3_600_000 ? `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s` : `${Math.floor(ms / 3_600_000)}h${Math.floor((ms % 3_600_000) / 60_000)}m`);
 /**
- * Was `head` gated by a PASS that existed at or before `at`?
+ * Was `head` gated by a typed PASS bound to it — in any channel, at any time?
  *
- * `at` is the decisive argument. Pass the merge time to ask "was this merge
- * gated"; pass `Date.now()` to ask "is this head gated right now", which is the
- * pre-merge question. Same predicate, two positions.
+ * `mergedAt` is DISCLOSURE, not a filter: when known and the earliest matching
+ * PASS postdates it, the answer is still gated and `verified` says by how long
+ * the record trailed the merge. The EARLIEST matching PASS is the one cited,
+ * so a PR comment that preceded the merge is not shadowed by a bus record that
+ * followed it (#309's shape).
  */
-export function gatedAt(verdicts: PassVerdict[], head: string, at: number): GateAnswer {
+export function gatedBy(verdicts: PassVerdict[], head: string, mergedAt: number | null = null): GateVerdict {
   const passes = verdicts.filter((v) => v.result === "pass");
   if (passes.length === 0) {
-    return { gated: false, reason: `no PASS verdict was ever recorded for this PR — not checked, which is not the same as checked and passing` };
+    return { gated: false, reason: `no typed PASS verdict exists for this PR in any channel — not checked, which is not the same as checked and passing` };
   }
-  const inTime = passes.filter((v) => v.ts <= at);
-  if (inTime.length === 0) {
+  const matches = passes.filter((v) => shaAgrees(v.head, head)).sort((a, b) => a.ts - b.ts);
+  const by = matches[0];
+  if (!by) {
     return {
       gated: false,
-      reason:
-        `every PASS for this PR was recorded AFTER the moment being judged — a verdict posted later says the content ` +
-        `was verified, never that this merge was gated`,
-      crossed: passes.map((v) => ({ gatedSha: v.head, at: v.ts })),
+      reason: `the head being judged (${head.slice(0, 7)}) matches no typed PASS in any channel — the thing merged is not the thing gated`,
+      crossed: passes.map((v) => ({ gatedSha: v.head, at: v.ts, channel: v.channel ?? "bus" })),
     };
   }
-  const match = inTime.find((v) => shaAgrees(v.head, head));
-  if (match) return { gated: true, by: match };
-  return {
-    gated: false,
-    reason:
-      `the head being judged (${head.slice(0, 7)}) matches no PASS recorded at or before that moment — ` +
-      `the thing merged is not the thing gated`,
-    crossed: inTime.map((v) => ({ gatedSha: v.head, at: v.ts })),
-  };
+  const lateByMs = mergedAt !== null && Number.isFinite(mergedAt) ? Math.max(0, by.ts - mergedAt) : null;
+  // ⟨q-6f4a19c8⟩ — the seat-naming record, when the earliest match cannot name one.
+  const seatRecord = by.channel === "pr" ? matches.find((v) => v.channel !== "pr") : undefined;
+  const gater = seatRecord ? gaterOf(seatRecord) : gaterOf(by);
+  const attribution: "seat" | "account" = by.channel === "pr" && !seatRecord ? "account" : "seat";
+  const scribed = (v: PassVerdict) => (v.gatedBy && v.gatedBy !== v.from ? `, scribed by ${v.from}` : "");
+  const who = seatRecord
+    ? `${gater} (bus${scribed(seatRecord)}), first seen on the PR at ${new Date(by.ts).toISOString()} as ${by.from}`
+    : by.channel === "pr"
+      ? `${by.from} (on the PR — a shared account, not a seat; no bus verdict names this head)`
+      : `${gater} (on the bus${scribed(by)})`;
+  const verified =
+    lateByMs === null
+      ? `verified at head ${head.slice(0, 7)} by ${who}`
+      : lateByMs > 0
+        ? `verified at head ${head.slice(0, 7)} by ${who}; the verdict was RECORDED ${fmtLate(lateByMs)} AFTER the merge — the content was judged, the merge was not covered when it happened`
+        : `verified at head ${head.slice(0, 7)} by ${who} before the merge`;
+  return { gated: true, by, lateByMs, verified, gater, attribution, ...(seatRecord ? { seatRecord } : {}) };
+}
+
+/**
+ * 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.
+ */
+export const VERDICT_COMMENT = /^(?:QA GATE|\*\*GATE|GATE)\b[^\n]*?\b(PASS|FAIL)\b(?:\s*\([^)\n]*\))?[^\n]*?@\s*`?([0-9a-f]{7,40})`?/;
+export function verdictShasIn(comments: { body: string }[]): { result: string; sha: string }[] {
+  const out: { result: string; sha: string }[] = [];
+  for (const c of comments) {
+    for (const line of String(c.body ?? "").split("\n")) {
+      const m = VERDICT_COMMENT.exec(line);
+      if (m) out.push({ result: m[1]!.toUpperCase(), sha: m[2]! });
+    }
+  }
+  return out;
+}
+/** PR comments as verdict records — the second channel. A comment with no typed line yields nothing. */
+export function prVerdictsIn(comments: { body: string; createdAt?: string; author?: string }[]): PassVerdict[] {
+  const out: PassVerdict[] = [];
+  for (const c of comments) {
+    for (const v of verdictShasIn([c])) {
+      out.push({ head: v.sha, ts: Date.parse(String(c.createdAt ?? "")) || 0, from: String(c.author ?? "pr-comment"), result: v.result.toLowerCase(), channel: "pr" });
+    }
+  }
+  return out;
 }

package/src/server-spread.ts

@@ -0,0 +1,233 @@
+/*
+ * ⛔⛆⛆ TWO SEATS RAN THE SAME VERB, GOT `153` AND `138`, AND BOTH SERVERS HONESTLY
+ * REPORTED `versionLabel 0.26.20` — `⟨q-cec42e20⟩`.
+ *
+ * Measured 2026-09-12: the aide's server (pid 61459, started 08:20:48Z) returned
+ * `parsedOpen 153` with a `delivered` axis; the coordinator's (pid 65516, started
+ * 2026-09-11T09:40:42Z) returned `open 138` and NO `delivered` axis at all. Identical
+ * labels, different loaded code, both answering honestly.
+ *
+ * ⭐⭐ THE LABEL IS NOT MERELY UNINFORMATIVE — IT IS ACTIVELY MISLEADING, because it is
+ * the ONE FIELD a seat reaches for to check exactly this, and it AGREES while the
+ * behaviour differs. Nothing detected the spread; every seat had to VOLUNTEER it. Five
+ * unprompted self-reports are why nothing broke that day, and a system that works
+ * because its operators are honest is one incident away from working because they were.
+ *
+ * ⛔ SO THIS DOES NOT KEY ON `versionLabel`, AND IT DOES NOT KEY ON `serverBuildMtime`
+ * EITHER — which is the near-miss worth recording, because that field LOOKS like the
+ * answer. It is stamped at ATTACH, and measured across all six live transports it held
+ * ONE distinct value (2026-09-11T09:27:20) for every seat. It would have reported the
+ * fleet uniform while the spread was live: `versionLabel`'s failure in a different field.
+ *
+ * ⭐ THE AXIS THAT DISCRIMINATES IS START TIME AGAINST THE INSTALLED BUILD — BUT ONLY
+ * FOR A SERVER THAT IS RUNNING THAT BUILD, AND THAT PROVISO IS NOT PEDANTRY. A server
+ * loads its code once, at spawn, so one that started BEFORE the current install runs
+ * different code from one that started AFTER it, whatever either calls itself.
+ *
+ * ⛔⛆ THE THIRD NEAR-MISS, AND THIS ONE WAS NOT A NEAR-MISS — IT WAS MEASURED ON THIS
+ * FILE. When `agent-coord-mcp@0.26.21` was installed at 2026-09-14T11:19:30Z, the
+ * time-only version of this module was run against the REAL population:
+ *
+ *     SERVER SPREAD: AGREED — 12 seat(s) placed, 0 unreadable
+ *       pre-install: (all twelve)
+ *
+ * AGREED. Over a fleet loading THREE DISTINCT BUILDS: nine on the installed one, two on
+ * a dev `dist/` in the primary checkout, and one on `0.19.1` from July. Every seat had
+ * started before the install, so every seat landed in one cohort and the fleet read
+ * uniform — `versionLabel`'s failure a THIRD time, now in the field this module chose
+ * as its remedy. "Which side of the install did you start" is not even a question about
+ * a server that never loads the installed build.
+ *
+ * ⭐ SO THE MODULE PATH IS THE PRIMARY KEY AND THE TIMESTAMP IS SUBORDINATE TO IT. A
+ * seat on a different build is its own cohort and is never folded into `pre-install`;
+ * a seat that does not publish a module path is UNCOMPARABLE, because it cannot be
+ * shown to be running the installed build at all. Today that makes the honest answer
+ * CANNOT_COMPARE for the whole fleet — which is the correct answer, and the one the
+ * time-only axis was hiding behind a clean AGREED.
+ */
+
+/** What one seat publishes about the process actually answering for it. */
+export type ServerIdentity = {
+  agentId: string;
+  /** The ANSWERING process. Never the pusher — that is a different process (⟨q-f14692ca⟩). */
+  serverPid?: number;
+  /** Epoch ms at which that process began. Captured from uptime, not from a file. */
+  serverStartedAt?: number;
+  /**
+   * The module root the answering process is EXECUTING, resolved from its own location.
+   * ⛔ Absent is not "the installed one" — it is unknown, and it makes the seat
+   * uncomparable rather than silently placing it with the majority.
+   */
+  serverModule?: string;
+};
+
+/** What the answering process was installed from: both halves, or nothing. */
+export type InstalledBuild = { mtime: number; module: string };
+
+export type SpreadVerdict =
+  | { state: "AGREED"; cohorts: Cohort[]; comparable: string[]; uncomparable: Uncomparable[] }
+  | { state: "DIVERGED"; cohorts: Cohort[]; comparable: string[]; uncomparable: Uncomparable[] }
+  | { state: "CANNOT_COMPARE"; why: string; cohorts: Cohort[]; comparable: string[]; uncomparable: Uncomparable[] };
+
+export type Cohort = { side: "pre-install" | "post-install" | "other-build"; agents: string[]; module?: string };
+export type Uncomparable = { agentId: string; why: string };
+
+/**
+ * Which side of the installed build a seat's server started on.
+ *
+ * ⚠ EXCLUSIVE ON PURPOSE: a server started at exactly the install's mtime is counted
+ * POST. The boundary belongs to one side or the other and putting it with the newer
+ * build is the direction that under-reports divergence rather than inventing it.
+ */
+const sideOf = (startedAt: number, installMtime: number): Cohort["side"] =>
+  startedAt < installMtime ? "pre-install" : "post-install";
+
+/**
+ * Do the live seats' servers disagree about what they are running?
+ *
+ * ⛔ THREE OUTCOMES, AND THE THIRD IS NOT A KIND OF AGREEMENT. A seat that publishes no
+ * identity cannot be placed, and reporting AGREED over a population you could not read
+ * is the defect this row exists to end — it is `exit 0` meaning "asked and resolved" and
+ * "never reached the registry" at once, one layer up.
+ *
+ * ⭐ SO AN UNREADABLE SEAT POISONS THE VERDICT RATHER THAN BEING DROPPED FROM IT: with
+ * any seat uncomparable the answer is CANNOT_COMPARE, even when every seat that COULD be
+ * read agrees. The cohorts are still returned, so a reader sees what was established as
+ * well as what was not.
+ */
+export function detectSpread(
+  identities: ServerIdentity[],
+  installed: InstalledBuild | null,
+): SpreadVerdict {
+  const uncomparable: Uncomparable[] = [];
+  const placed: { agentId: string; side: Cohort["side"]; module?: string }[] = [];
+
+  for (const id of identities) {
+    // ⛔ THE MODULE PATH IS READ FIRST, and a missing one is not a default. A seat that
+    // does not say what it is running cannot be compared against the installed build,
+    // and placing it by timestamp alone is exactly the AGREED-over-three-builds result.
+    if (typeof id.serverModule !== "string" || !id.serverModule) {
+      uncomparable.push({
+        agentId: id.agentId,
+        why: "publishes no module path — it cannot be shown to be running the installed build at all, and a timestamp cannot answer that",
+      });
+      continue;
+    }
+    if (typeof id.serverStartedAt !== "number" || !Number.isFinite(id.serverStartedAt)) {
+      uncomparable.push({
+        agentId: id.agentId,
+        why: "no serverStartedAt published — this seat's server has not stamped its identity since the field existed",
+      });
+      continue;
+    }
+    if (installed === null) continue;
+    // ⭐ A DIFFERENT BUILD IS ITS OWN COHORT, never folded into `pre-install`: "which
+    // side of the install did you start" is not a question about a process that does
+    // not load the install. Measured 2026-09-14 — 3 of 12 seats were in this case.
+    if (id.serverModule !== installed.module) {
+      placed.push({ agentId: id.agentId, side: "other-build", module: id.serverModule });
+      continue;
+    }
+    placed.push({ agentId: id.agentId, side: sideOf(id.serverStartedAt, installed.mtime) });
+  }
+
+  const cohorts: Cohort[] = [];
+  for (const side of ["pre-install", "post-install"] as const) {
+    const agents = placed.filter((p) => p.side === side).map((p) => p.agentId).sort();
+    if (agents.length) cohorts.push({ side, agents });
+  }
+  // One cohort PER FOREIGN BUILD, so two seats on different foreign builds never read
+  // as one group that agrees with itself.
+  for (const module of [...new Set(placed.filter((p) => p.side === "other-build").map((p) => p.module!))].sort()) {
+    cohorts.push({
+      side: "other-build",
+      module,
+      agents: placed.filter((p) => p.module === module).map((p) => p.agentId).sort(),
+    });
+  }
+  const comparable = placed.map((p) => p.agentId).sort();
+
+  if (installed === null) {
+    return {
+      state: "CANNOT_COMPARE",
+      why: "the installed build could not be read, so no seat can be placed against it",
+      cohorts,
+      comparable,
+      uncomparable,
+    };
+  }
+  if (uncomparable.length) {
+    return {
+      state: "CANNOT_COMPARE",
+      why:
+        `${uncomparable.length} of ${identities.length} live seat(s) publish no usable server identity, so the fleet ` +
+        `cannot be shown uniform — what the readable seats agree about is reported, but it is not an answer about the fleet`,
+      cohorts,
+      comparable,
+      uncomparable,
+    };
+  }
+  if (comparable.length < 2) {
+    return {
+      state: "CANNOT_COMPARE",
+      why: `only ${comparable.length} seat(s) could be placed — a disagreement needs two parties`,
+      cohorts,
+      comparable,
+      uncomparable,
+    };
+  }
+  return { state: cohorts.length > 1 ? "DIVERGED" : "AGREED", cohorts, comparable, uncomparable };
+}
+
+/**
+ * What a reader is told. The POPULATION is mandatory for the same reason the replay
+ * instrument's is (⟨q-a83b56af⟩): "0 diverged of 6 read" and "0 of 0" are different
+ * facts and only the second is a reason to distrust the run.
+ */
+export function reportSpread(v: SpreadVerdict, installed: InstalledBuild | null): string {
+  const iso = (ms: number) => new Date(ms).toISOString();
+  const lines = [
+    `SERVER SPREAD: ${v.state} — ${v.comparable.length} seat(s) placed, ${v.uncomparable.length} unreadable` +
+      (installed === null
+        ? " · installed build UNREADABLE"
+        : ` · installed build ${iso(installed.mtime)} ${installed.module}`),
+  ];
+  if ("why" in v) lines.push(`  ⛔ ${v.why}`);
+  for (const c of v.cohorts) {
+    lines.push(`  ${c.side}${c.module ? ` (${c.module})` : ""}: ${c.agents.join(", ")}`);
+  }
+  for (const u of v.uncomparable) lines.push(`  ⚠ ${u.agentId}: ${u.why}`);
+  if (v.state === "DIVERGED") {
+    lines.push(
+      `  These seats are running DIFFERENT CODE. A version label will agree anyway — it did`,
+      `  on 2026-09-12 while one server answered 153 and the other 138.`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The build this process was INSTALLED from — its module root AND its mtime — or null.
+ *
+ * ⛔ NULL IS A REAL ANSWER AND MUST STAY ONE. If this cannot be read, no seat can be
+ * placed on either side of it and the only truthful verdict is CANNOT_COMPARE —
+ * returning a 0 or a now() would place every seat on one side and report the fleet
+ * uniform, which is the failure this whole row is about.
+ *
+ * Resolved from THIS module's own location rather than from a configured path: the
+ * question is "what build is the answering process running", and the answering process
+ * is the one executing this file.
+ */
+export function installedBuild(
+  fromUrl: string,
+  statSync: (p: string) => { mtimeMs: number },
+): InstalledBuild | null {
+  try {
+    // dist/server-spread.js -> the package root two levels up
+    const here = new URL(fromUrl).pathname;
+    const root = here.replace(/\/dist\/[^/]*$/, "");
+    return { mtime: statSync(`${root}/package.json`).mtimeMs, module: root };
+  } catch {
+    return null;
+  }
+}

package/src/server.ts

@@ -445,7 +445,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "send_message",
-    "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured. EVERY AGENT→AGENT MESSAGE MUST CARRY 'record' with a typed 'type' (decision · verdict · done · blocker · risk · fyi · action · go · scope): a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle, while an untyped one arrives in full in every reader's context. 'fyi' is the honest catch-all — use it rather than forcing a false 'decision'/'risk'. Untyped sends WARN today and are REFUSED from 2026-09-15. Messages TO a human are exempt (David-facing traffic stays prose), as is a sender that declared proseOnly:true at join.",
+    "Send a message. A `done` record cites its PR, or — for work that has no PR by rule — a full commit sha with `repo` (verified reachable from origin/main, no network). If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured. EVERY AGENT→AGENT MESSAGE MUST CARRY 'record' with a typed 'type' (decision · verdict · done · blocker · risk · fyi · action · go · scope): a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle, while an untyped one arrives in full in every reader's context. 'fyi' is the honest catch-all — use it rather than forcing a false 'decision'/'risk'. Untyped sends WARN today and are REFUSED from 2026-09-15. Messages TO a human are exempt (David-facing traffic stays prose), as is a sender that declared proseOnly:true at join.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -631,7 +631,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "stall_check",
-    "The stall predicate over the board and the bus: a 🚧 In Progress or 🔍 In Review row (both are lanes somebody is working; a review that never gets re-gated is the stall shape of a QA-gated fleet) whose agent's heartbeat is older than the window, or whose claimed branch has no commits in it. HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.",
+    "The stall predicate over the board and the bus: a 🚧 In Progress or 🔍 In Review row (both are lanes somebody is working; a review that never gets re-gated is the stall shape of a QA-gated fleet) whose agent's heartbeat is older than the window, or — for 🚧 — whose claimed branch has no commits in the window; a 🔍 row is scored on TIME IN REVIEW read from the board's git history (`reviewMinutes`, default 120), never on branch activity, because a branch under review is frozen for the correct reason. Every scored row carries its board freshness (when its line was last written). HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.",
     stallCheckSchema,
     gate(null, stallCheckTool as (a: Record<string, unknown>) => Promise<unknown>),
   );

package/src/store.ts

@@ -9,6 +9,38 @@ export const ROOT =
   process.env.CLAUDE_COORD_DIR ??
   path.join(homedir(), "agent-coord");
 export const AGENTS_FILE = path.join(ROOT, "agents.json");
+/**
+ * ⟨q-178878aa⟩ — THE HUMANS THE BUS KNOWS, durably. A human is not an agent: no pusher, no
+ * heartbeat, so a registry entry for one is evicted after EVICT_MS and the typed-record
+ * exemption ("messages TO a human are exempt") could not see the one human it exists for —
+ * the first David-facing send after the cutover was refused. This file is written when a
+ * seat registers with a human role and never evicted; `AGENT_COORD_HUMANS` (comma list)
+ * names humans for a store nobody has registered them in yet. Read at SEND time.
+ */
+export const HUMANS_FILE = path.join(ROOT, "humans.json");
+export type HumanEntry = { since: number; displayName?: string; by?: string };
+export type HumanRegistry = Record<string, HumanEntry>;
+export function envHumans(): string[] {
+  return String(process.env.AGENT_COORD_HUMANS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+/** Every known human: the durable file, unioned with the environment list (`by: "env"`). */
+export async function readHumans(): Promise<HumanRegistry> {
+  const file = await readJson<HumanRegistry>(HUMANS_FILE, {});
+  const out: HumanRegistry = { ...file };
+  for (const id of envHumans()) if (!out[id]) out[id] = { since: 0, by: "env" };
+  return out;
+}
+export async function isKnownHuman(id: string): Promise<boolean> {
+  return Boolean((await readHumans())[id]);
+}
+/** Record a human durably; an existing entry keeps its `since`. */
+export async function recordHuman(id: string, meta: { displayName?: string; by?: string } = {}): Promise<HumanEntry> {
+  const reg = await updateJson<HumanRegistry>(HUMANS_FILE, {}, (cur) => {
+    cur[id] = { since: cur[id]?.since ?? Date.now(), ...(meta.displayName ? { displayName: meta.displayName } : {}), ...(meta.by ? { by: meta.by } : {}) };
+    return cur;
+  });
+  return reg[id];
+}
 export const ROOM_FILE = path.join(ROOT, "room.jsonl");
 export const STATUS_FILE = path.join(ROOT, "status.jsonl");
 export const INBOX_DIR = path.join(ROOT, "inbox");