agent-coord-mcp 0.26.36 → 0.26.40

package/src/launch-unit.ts

@@ -0,0 +1,350 @@
+/*
+ * ⟨q-6d37c349⟩ A NAMED SCHEDULER UNIT THAT EXISTS, RATHER THAN ONE THAT IS DOCUMENTED.
+ *
+ * Both clocks in this package already argued the right thing in their own headers — a timer, not a
+ * trigger, because "a mechanism without a schedule measures inbound traffic rather than elapsed time
+ * and cannot fire during exactly the quiet it exists to cover". Both then named a launchd label in a
+ * comment and made `--install` PRINT a plist to stdout with instructions for a human.
+ *
+ * MEASURED 2026-09-26, and this is the whole reason this file exists: `launchctl print
+ * gui/501/<label>` exits 113 for BOTH `com.davidbalzan.coord-stall-clock` and
+ * `com.davidbalzan.coord-attention-clock`, and `~/Library/LaunchAgents` holds no plist for either.
+ * Neither was ever installed. So every one of the stall clock's 200 recorded runs was a HAND run by
+ * whoever last polled it, and `stall_clock_status` read "THE CLOCK IS STOPPED" at 9860m on 09-23 and
+ * again at 2523m on 09-26. ⛔ THE UNIT WAS NAMED IN DOCUMENTATION, NOT CREATED — the
+ * instrument-for-property substitution, one level above the code it was written to prevent.
+ *
+ * ⛔ SO "INSTALLED" MEANS LOADED, AND IT IS READ BACK FROM launchd. Writing the plist is not
+ * installing it; bootstrapping without checking is not either. `installUnit` writes, bootstraps, then
+ * ASKS launchctl and REFUSES unless the label answers. The instrument is validated in both directions
+ * before it is trusted: exit 0 for `com.davidbalzan.agent-coord-http`, which everyone agrees is
+ * loaded, and 113 for a label nobody has installed.
+ *
+ * Everything here takes its `run` and its filesystem as arguments so a test can drive the refusal
+ * paths without touching this machine's launchd, and one live test can prove the real thing.
+ */
+import { homedir } from "node:os";
+import path from "node:path";
+
+/** What a process runner must answer. Injected everywhere, so nothing here reaches launchd by itself. */
+export type RunResult = { status: number | null; stdout: string; stderr: string };
+export type Runner = (cmd: string, args: string[]) => RunResult;
+
+export type UnitFs = {
+  writeFileSync: (p: string, data: string) => void;
+  mkdirSync: (p: string, opts: { recursive: true }) => void;
+  existsSync: (p: string) => boolean;
+  readFileSync: (p: string, enc: "utf8") => string;
+  rmSync: (p: string, opts: { force: true }) => void;
+};
+
+/** `~/Library/LaunchAgents/<label>.plist` — where a per-user agent lives on macOS. */
+export function unitPath(label: string, home: string = homedir()): string {
+  return path.join(home, "Library", "LaunchAgents", `${label}.plist`);
+}
+
+/**
+ * The calling user's uid, which names the `gui/<uid>` domain a per-user agent is filed under.
+ *
+ * ⛔ A DIRECT call, deliberately NOT an optional call on `getuid` with a `?? 0` fallback (LESSONS #41,
+ * and note the guard is line-based so this sentence must not spell the banned form). `getuid` is POSIX-only
+ * and @types/node therefore declares it optional, which is what invites the optional call — but every
+ * caller in this module refuses on non-darwin before reaching here, so its absence is not a case to
+ * tolerate. And the fallback the optional form wants is `0`, which is ROOT's domain: the one uid a
+ * per-user LaunchAgent must never be installed into. Throwing beats installing into the wrong domain.
+ */
+export function ownUid(): number {
+  if (typeof process.getuid !== "function") {
+    throw new Error("launch-unit: process.getuid is unavailable — this module is darwin-only and must not guess a uid");
+  }
+  return process.getuid();
+}
+
+/** launchd's own name for a per-user service. `gui/<uid>/<label>` is what `launchctl print` takes. */
+export function serviceTarget(label: string, uid: number = ownUid()): string {
+  return `gui/${uid}/${label}`;
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/**
+ * The plist text. `StartInterval` is what makes it a timer; `RunAtLoad` makes the first run happen at
+ * boot rather than one interval later.
+ *
+ * ⛔ NO `KeepAlive`. The bus daemon uses it because it is a long-lived server that should be restarted
+ * when it dies; a clock is a SHORT-LIVED command that exits after each tick, and `KeepAlive` on one
+ * tells launchd to relaunch it immediately, forever. The precedent is cited for the fact that a
+ * LaunchAgent is the thing that runs unattended here, not for its restart policy.
+ */
+export function plistFor(args: {
+  label: string;
+  program: string;
+  programArgs: string[];
+  startIntervalSec: number;
+  stderrPath?: string;
+  stdoutPath?: string;
+}): string {
+  const items = [args.program, ...args.programArgs].map((a) => `    <string>${esc(a)}</string>`).join("\n");
+  const err = args.stderrPath ? `\n  <key>StandardErrorPath</key><string>${esc(args.stderrPath)}</string>` : "";
+  const out = args.stdoutPath ? `\n  <key>StandardOutPath</key><string>${esc(args.stdoutPath)}</string>` : "";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${esc(args.label)}</string>
+  <key>ProgramArguments</key><array>
+${items}
+  </array>
+  <key>StartInterval</key><integer>${args.startIntervalSec}</integer>
+  <key>RunAtLoad</key><true/>${err}${out}
+</dict></plist>
+`;
+}
+
+export type LoadState = { loaded: boolean; evidence: string };
+
+/**
+ * IS THIS LABEL LOADED? Asked of launchd, never inferred from a file on disk.
+ *
+ * A plist in `~/Library/LaunchAgents` that nobody bootstrapped is exactly as inert as no plist at all,
+ * and it looks more installed. Measured on this machine: exit 0 for a loaded label, 113 for an absent
+ * one — both directions, before this was trusted.
+ */
+export function isLoaded(label: string, run: Runner, uid?: number): LoadState {
+  const target = serviceTarget(label, uid);
+  const r = run("launchctl", ["print", target]);
+  if (r.status === 0) return { loaded: true, evidence: `launchctl print ${target} exited 0` };
+  const why = (r.stderr || r.stdout || "").trim().split("\n")[0] ?? "";
+  return { loaded: false, evidence: `launchctl print ${target} exited ${r.status}${why ? ` — ${why}` : ""}` };
+}
+
+export type InstallResult = {
+  ok: boolean;
+  label: string;
+  plistPath: string;
+  action: "bootstrapped" | "replaced" | "already-loaded" | "refused";
+  loaded: boolean;
+  evidence: string;
+  why?: string;
+};
+
+/**
+ * WRITE, BOOTSTRAP, THEN READ LAUNCHD BACK — and refuse if the label does not answer.
+ *
+ * `bootstrap` is not idempotent: bootstrapping an already-loaded label errors, so an existing unit is
+ * booted out first when its plist content differs, and left alone when it does not. The return says
+ * which of those happened, because "already-loaded" and "bootstrapped" are different facts and a
+ * caller that cannot tell them apart will report a no-op as an install.
+ */
+export function installUnit(
+  spec: { label: string; program: string; programArgs: string[]; startIntervalSec: number; stderrPath?: string; stdoutPath?: string },
+  io: { run: Runner; fs: UnitFs; home?: string; uid?: number; store?: string },
+): InstallResult {
+  const { run, fs } = io;
+  const label = spec.label;
+  const plistPath = unitPath(label, io.home ?? homedir());
+  const target = serviceTarget(label, io.uid);
+  const wanted = plistFor(spec);
+  const before = isLoaded(label, run, io.uid);
+
+  const current = fs.existsSync(plistPath) ? fs.readFileSync(plistPath, "utf8") : null;
+  if (before.loaded && current === wanted) {
+    // The receipt is (re)written here too: a machine whose unit is loaded but whose receipt was lost
+    // would otherwise read as never-installed the moment the unit went away.
+    if (io.store) writeReceipt(io.store, { label, plistPath, at: new Date().toISOString(), program: spec.program }, fs);
+    return { ok: true, label, plistPath, action: "already-loaded", loaded: true, evidence: before.evidence };
+  }
+
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  fs.writeFileSync(plistPath, wanted);
+
+  let action: InstallResult["action"] = "bootstrapped";
+  if (before.loaded) {
+    run("launchctl", ["bootout", target]);
+    action = "replaced";
+  }
+  const boot = run("launchctl", ["bootstrap", `gui/${io.uid ?? ownUid()}`, plistPath]);
+
+  // ⛔ THE READBACK. A zero exit from `bootstrap` is not evidence the unit is loaded, and a non-zero
+  // one is not evidence it is absent — so the verdict comes from asking, either way.
+  const after = isLoaded(label, run, io.uid);
+  if (!after.loaded) {
+    return {
+      ok: false,
+      label,
+      plistPath,
+      action: "refused",
+      loaded: false,
+      evidence: after.evidence,
+      why:
+        `wrote ${plistPath} and ran launchctl bootstrap (exit ${boot.status}${(boot.stderr || "").trim() ? `: ${(boot.stderr || "").trim().split("\n")[0]}` : ""}), ` +
+        `but launchd does not report the label as loaded. NOTHING IS SCHEDULED. A plist on disk that was never ` +
+        `bootstrapped is exactly as inert as no plist at all, and it looks more installed.`,
+    };
+  }
+  if (io.store) {
+    writeReceipt(io.store, { label, plistPath, at: new Date().toISOString(), program: spec.program }, fs);
+  }
+  return { ok: true, label, plistPath, action, loaded: true, evidence: after.evidence };
+}
+
+/** Boot the label out and remove its plist. Reports what was actually there, not what was asked for. */
+export function uninstallUnit(label: string, io: { run: Runner; fs: UnitFs; home?: string; uid?: number; store?: string }): {
+  ok: boolean;
+  label: string;
+  wasLoaded: boolean;
+  stillLoaded: boolean;
+  plistRemoved: boolean;
+  receiptDropped: boolean;
+  evidence: string;
+} {
+  const plistPath = unitPath(label, io.home ?? homedir());
+  const before = isLoaded(label, io.run, io.uid);
+  if (before.loaded) io.run("launchctl", ["bootout", serviceTarget(label, io.uid)]);
+  const removed = io.fs.existsSync(plistPath);
+  if (removed) io.fs.rmSync(plistPath, { force: true });
+  const after = isLoaded(label, io.run, io.uid);
+  const receiptDropped = io.store ? dropReceipt(io.store, label, io.fs) : false;
+  return { ok: !after.loaded, label, wasLoaded: before.loaded, stillLoaded: after.loaded, plistRemoved: removed, receiptDropped, evidence: after.evidence };
+}
+
+/**
+ * EVERY UNIT THIS PACKAGE DECLARES, DERIVED FROM THE SCRIPTS THAT DECLARE THEM.
+ *
+ * ⛔ NOT A LIST IN THIS FILE. A guard whose population is a hardcoded list stops finding things — the
+ * same defect ⟨q-68b91bf7⟩ is open for in `packaging.mjs`, where a 14-name literal meant a new skill
+ * shipped unverified. A third clock added next month is covered here without anyone remembering to
+ * add it, and a clock whose label is renamed is followed automatically.
+ */
+export function declaredUnits(scriptsDir: string, fs: Pick<UnitFs, "readFileSync"> & { readdirSync: (p: string) => string[] }): {
+  label: string;
+  script: string;
+}[] {
+  const out: { label: string; script: string }[] = [];
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(scriptsDir);
+  } catch {
+    return out;
+  }
+  for (const name of names.sort()) {
+    if (!name.endsWith(".mjs")) continue;
+    let src = "";
+    try {
+      src = fs.readFileSync(path.join(scriptsDir, name), "utf8");
+    } catch {
+      continue;
+    }
+    // `const LABEL = "com.…"` is how both clocks declare theirs, and a declaration is a string
+    // literal assigned to LABEL — not any mention of a label, which comments also contain.
+    const m = /^\s*const\s+LABEL\s*=\s*["'`]([A-Za-z0-9.\-_]+)["'`]/m.exec(src);
+    if (m) out.push({ label: m[1], script: name });
+  }
+  return out;
+}
+
+/* ── the receipt: what THIS MACHINE has ever had installed ───────────────────────────────────────── */
+
+/**
+ * ⛔ WHY A RECEIPT EXISTS AT ALL, because it is the difference between two states that look identical on
+ * disk and mean opposite things: a machine that NEVER installed a clock, and a machine where one was
+ * installed and has since stopped existing. The first is a decision nobody has taken yet — installing a
+ * LaunchAgent on someone's machine is theirs to authorise, and the last hop of an idle-fleet alarm is
+ * still David's open question. The second is a REGRESSION, and it is the case ⟨q-6d37c349⟩ was opened
+ * for: something that used to run stopped running and nothing said so for two days.
+ *
+ * So `installUnit` leaves a receipt and `uninstallUnit` removes it — an intentional uninstall is not a
+ * regression — and the check refuses only where a receipt and an absent unit disagree.
+ */
+export const receiptPath = (store: string) => path.join(store, "clock-units.json");
+
+export type Receipt = { label: string; plistPath: string; at: string; program: string };
+
+/**
+ * ⛔ AN UNREADABLE RECEIPT IS NOT "NO RECEIPT", AND THE RETURN SHAPE IS WHAT MAKES THAT UNMISSABLE.
+ *
+ * The first version of this returned a bare `{}` on a parse failure with a comment claiming the caller
+ * would know — it would not have. Silently downgrading a corrupt receipt to never-installed turns the
+ * one case this check refuses (a clock that used to run and stopped) into the case it merely warns
+ * about. So `unreadable` is a field, and a caller that cannot answer says so instead of guessing.
+ */
+export function readReceipts(
+  store: string,
+  fs: Pick<UnitFs, "existsSync" | "readFileSync">,
+): { receipts: Record<string, Receipt>; unreadable: string | null } {
+  const f = receiptPath(store);
+  if (!fs.existsSync(f)) return { receipts: {}, unreadable: null };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(f, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { receipts: {}, unreadable: `${f} does not hold a JSON object` };
+    }
+    return { receipts: parsed as Record<string, Receipt>, unreadable: null };
+  } catch (e) {
+    return { receipts: {}, unreadable: `${f} could not be parsed: ${(e as Error).message}` };
+  }
+}
+
+export function writeReceipt(store: string, r: Receipt, fs: Pick<UnitFs, "existsSync" | "readFileSync" | "writeFileSync" | "mkdirSync">): void {
+  const { receipts: all } = readReceipts(store, fs);
+  all[r.label] = r;
+  fs.mkdirSync(store, { recursive: true });
+  fs.writeFileSync(receiptPath(store), `${JSON.stringify(all, null, 2)}\n`);
+}
+
+export function dropReceipt(store: string, label: string, fs: Pick<UnitFs, "existsSync" | "readFileSync" | "writeFileSync" | "mkdirSync">): boolean {
+  const { receipts: all } = readReceipts(store, fs);
+  if (!(label in all)) return false;
+  delete all[label];
+  fs.mkdirSync(store, { recursive: true });
+  fs.writeFileSync(receiptPath(store), `${JSON.stringify(all, null, 2)}\n`);
+  return true;
+}
+
+/* ── loaded is not working ───────────────────────────────────────────────────────────────────────── */
+
+export type LastRun = {
+  runs: number | null;
+  lastExitCode: number | null;
+  evidence: string;
+  unmeasured: string | null;
+};
+
+/**
+ * ⛔ DID ITS LAST RUN SUCCEED? A UNIT CAN BE LOADED AND FAILING EVERY TICK.
+ *
+ * MEASURED 2026-09-26, on my own mistake: an `--install` test of mine put this package's stall clock
+ * into launchd pointed at `--repo=/tmp/x`, and it fired 9 times over four hours, every 30 minutes, and
+ * FAILED every one. `check-clock-units-loaded` passed it the whole time, because it asked whether the
+ * unit was LOADED and the unit was loaded. The verb that caught it was `stall_clock_status`: "it is
+ * firing on schedule and measuring nothing, which reads as fresh and is not."
+ *
+ * ⛔ AND THE INSTRUMENT IS launchd's OWN RECORD, not a per-clock mark file. `launchctl print` reports
+ * `runs = <n>` and `last exit code = <n>` for every unit it has ever started — so this works for a
+ * clock that keeps no marks, and needs no map from label to log. A map would be the hardcoded-population
+ * defect again, one layer down.
+ *
+ * Three answers, and the third is not the second: never run yet (`runs = 0`, nothing to judge), ran and
+ * succeeded, ran and failed. A field that cannot be parsed is UNMEASURED and says so.
+ */
+export function lastRun(label: string, run: Runner, uid?: number): LastRun {
+  const target = serviceTarget(label, uid);
+  const r = run("launchctl", ["print", target]);
+  if (r.status !== 0) {
+    return { runs: null, lastExitCode: null, evidence: `launchctl print ${target} exited ${r.status}`, unmeasured: "the unit is not loaded, so it has no run record here" };
+  }
+  const out = r.stdout ?? "";
+  // The FIRST match of each: `launchctl print` nests dictionaries, and the unit's own counters are at
+  // the top level. Taking the first is deliberate rather than incidental.
+  const runsM = /^\s*runs\s*=\s*(\d+)\s*$/m.exec(out);
+  const exitM = /^\s*last exit code\s*=\s*(-?\d+)\s*$/m.exec(out);
+  if (!runsM) {
+    return { runs: null, lastExitCode: null, evidence: `launchctl print ${target} exited 0 but reported no \`runs\` field`, unmeasured: "launchd did not report a run count — UNMEASURED, never assumed healthy" };
+  }
+  const runs = Number(runsM[1]);
+  const lastExitCode = exitM ? Number(exitM[1]) : null;
+  const evidence =
+    runs === 0
+      ? `launchctl print ${target}: runs = 0 — loaded and not yet fired`
+      : `launchctl print ${target}: runs = ${runs}, last exit code = ${lastExitCode === null ? "not reported" : lastExitCode}`;
+  return { runs, lastExitCode, evidence, unmeasured: runs > 0 && lastExitCode === null ? "launchd reported runs but no exit code — UNMEASURED" : null };
+}

package/src/server.ts

@@ -15,10 +15,12 @@ import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool }
 import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
 import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
 import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
+import { type AuthFault, logText, responseText, detailInResponse } from "./auth-faults.js";
 import {
   ensureDirs,
   getTokenMap,
   agentForBearer,
+  retiredBearerFor,
   tokenMapCensusLine,
   TOKENS_FILE,
   reloadTokenMapSync,
@@ -767,7 +769,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "subscribe",
-    "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate.",
+    "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate. SCOPE picks how widely you are asking and is an explicit field rather than a magic target: `exact` (the default, and what every subscription stored before this field meant) matches one target; `kind` matches every event of the kind and REFUSES a target, because a target that was accepted and ignored would read narrower than it behaves; `prefix` matches targets starting with yours — which is how you watch a class whose ids do not exist yet, e.g. `davidbalzan/groundwork-kit#` for one repo's PRs. A prefix is over whatever `target` holds FOR THAT KIND (`pr` the full ref, `item` the queue id, `task` the KEY rather than the ticked line, `phase` the phase), and an EMPTY prefix is refused because it would match everything — that is the wildcard this field exists to avoid spelling in-band; ask for `kind` and say so.",
     subscribeSchema,
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -854,6 +856,11 @@ function loadTokenMap(initial: boolean): void {
   }
 }
 
+/** The coord dir, for the bind-time log line that tells an operator where refusals are recorded. */
+function coordRootForLog(): string {
+  return process.env.AGENT_COORD_DIR ?? `${process.env.HOME ?? "~"}/agent-coord`;
+}
+
 async function main() {
   ensureDirs();
   loadTokenMap(true);
@@ -1117,8 +1124,12 @@ async function startHttp(port: number): Promise<void> {
   // Reverse-lookup: extract bearer from header, map → bound agent. Returns
   // undefined if no map is configured (advisory mode); throws-like return of
   // null if the bearer doesn't match any known agent (caller responds 401).
-  function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string } {
-    if (!authHeader || !authHeader.startsWith("Bearer ")) return { ok: false };
+  function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string; fault?: AuthFault } {
+    // ⟨q-a441f1e1⟩ The refusal now carries WHICH fault it was. The caller is told only about the
+    // SHAPE of its request; everything about a credential's validity is uniform to the caller and
+    // detailed in the daemon log — see src/auth-faults.ts for why that split is where it is.
+    if (!authHeader) return { ok: false, fault: { kind: "no-header" } };
+    if (!authHeader.startsWith("Bearer ")) return { ok: false, fault: { kind: "not-bearer" } };
     const bearer = authHeader.slice("Bearer ".length);
     // ⟨q-54adf191⟩ Pick up a tokens.json that changed while this daemon ran. Rate-limited, so the
     // steady state is one stat; the file is read only when its stamp moved. Every outcome that is
@@ -1143,10 +1154,16 @@ async function startHttp(port: number): Promise<void> {
       // actually connects gets a tail, so a 20-agent map does not spawn 20 timers for seats that
       // may not exist. Idempotent — steady state is one Map lookup per request.
       if (agent) startTailOnBind(agent);
-      return agent ? { ok: true, agent } : { ok: false };
+      if (agent) return { ok: true, agent };
+      if (bearer === "") return { ok: false, fault: { kind: "empty-bearer" } };
+      // Retired is asked only AFTER the forced re-read above: a bearer minted seconds ago must not
+      // be reported as retired because this process had not read the file yet.
+      const retired = retiredBearerFor(bearer);
+      return { ok: false, fault: retired ? { kind: "retired-bearer", retired } : { kind: "unknown-bearer" } };
     }
     // Advisory mode: only check the shared bearer matches.
-    return sharedExpected && authHeader === sharedExpected ? { ok: true } : { ok: false };
+    if (sharedExpected && authHeader === sharedExpected) return { ok: true };
+    return { ok: false, fault: { kind: "advisory-mismatch" } };
   }
 
   // ⛔ ONE HANDLER, N SERVERS. Node binds a single address per `http.Server`, so a list of
@@ -1171,8 +1188,13 @@ async function startHttp(port: number): Promise<void> {
       // observe traffic; TLS termination is the answer to that.
       const resolved = resolveBoundAgent(req.headers.authorization);
       if (!resolved.ok) {
+        // ⟨q-a441f1e1⟩ The LOG is where an operator diagnosing "my seat stopped working" looks, and
+        // it distinguishes every fault. The RESPONSE names only what the caller already knows about
+        // its own request. Neither ever contains any part of a bearer.
+        const fault = resolved.fault ?? { kind: "unknown-bearer" as const };
+        console.error(`[agent-coord-mcp] ${logText(fault)}`);
         res.writeHead(401, { "Content-Type": "text/plain", "WWW-Authenticate": "Bearer" });
-        res.end("unauthorized\n");
+        res.end(`${responseText(fault)}\n`);
         return;
       }
 
@@ -1217,6 +1239,25 @@ async function startHttp(port: number): Promise<void> {
   {
     const startupCensus = tokenMapCensusLine();
     if (startupCensus) console.error(startupCensus);
+    // ⛔ ⟨q-a441f1e1⟩ A BUS RUNNING WITH THE ORACLE ON SAYS SO, AT BIND. qa: the switch existed and
+    // NOTHING announced it — no startup line, no warning — so a daemon could distinguish validity
+    // faults to unauthenticated callers while neither its log nor its capabilities mentioned it.
+    // An operator must not have to read the environment of a running process to learn this.
+    // ⭐ ⟨q-a441f1e1⟩ WHERE THE WITHHELD REASONS GO, stated at bind so an operator has the exact
+    // destination without it ever appearing in a 401 body. The response points at "this bus's daemon
+    // log" by role; this line is what turns that role into a path for the person entitled to it.
+    console.error(
+      `[agent-coord-mcp] 401 reasons (unknown / retired / advisory-mismatch bearers) are written HERE, to this ` +
+        `process's stderr — pid ${process.pid}, agent-coord dir ${coordRootForLog()}. A refused caller is told to ` +
+        `look here and is told nothing else.`,
+    );
+    if (detailInResponse()) {
+      console.error(
+        `[agent-coord-mcp] ⛔ AGENT_COORD_401_DETAIL=response — this bus tells an UNAUTHENTICATED caller ` +
+          `whether a bearer was never minted, or was genuine and retired, and when. That confirms a real ` +
+          `credential to whoever just failed to authenticate. Unset it to keep the detail in this log only.`,
+      );
+    }
   }
   await Promise.all(
     bindAddrs.map(

package/src/store.ts

@@ -392,8 +392,30 @@ export type TokenMapRefresh = {
   count: number | null;
   /** Present only when the reload was REFUSED; the previous map still serves. */
   refused?: string;
+  /**
+   * ⟨q-a441f1e1⟩ Bearers that were in the map before this reload and are not in it after — the only
+   * moment the daemon can ever observe a retirement, because nothing on disk records one.
+   * Hashes, never secrets. Empty unless `changed` is true.
+   */
+  retired?: RetiredHash[];
 };
 
+/** A bearer hash that left the map, with the agent it belonged to. ⛔ A HASH, NEVER A BEARER. */
+export type RetiredHash = { hash: string; agentId: string };
+
+/**
+ * ⟨q-a441f1e1⟩ Which entries LEFT the map. Pure, and separate from the reload decision so it can be
+ * exercised on posed maps: a rotation (`coord-token add` on an existing agent) and a revoke
+ * (`coord-token revoke`) both present here as a hash that is gone, and they are told apart by
+ * whether the agent still holds some other key afterwards.
+ */
+export function retiredSince(before: Map<string, string> | null, after: Map<string, string> | null): RetiredHash[] {
+  if (!before || !after) return [];
+  const out: RetiredHash[] = [];
+  for (const [hash, agentId] of before) if (!after.has(hash)) out.push({ hash, agentId });
+  return out;
+}
+
 // The file identity we compare against: mtime, size AND inode.
 //
 // ⛔ THE INODE IS LOAD-BEARING, NOT BELT-AND-BRACES. `coord-token` rotates by writing a temp file and
@@ -463,7 +485,12 @@ export function decideTokenMapRefresh(
     }
     return {
       next: { map: next, stamp, checkedAt: now },
-      result: { changed: true, reason: state.stamp === null ? "appeared" : "changed", count: next.size },
+      result: {
+        changed: true,
+        reason: state.stamp === null ? "appeared" : "changed",
+        count: next.size,
+        retired: retiredSince(state.map, next),
+      },
     };
   } catch (e) {
     // The stamp is deliberately NOT advanced: a half-written file that is fixed in place, with no
@@ -472,6 +499,58 @@ export function decideTokenMapRefresh(
   }
 }
 
+/**
+ * ⟨q-a441f1e1⟩ — WHAT THIS PROCESS WATCHED LEAVE THE TOKEN MAP. Hash → who held it and when it went.
+ *
+ * ⛔ IN MEMORY, DELIBERATELY, AND IT FORGETS ON RESTART. Nothing on disk records a superseded token:
+ * `coord-token add` overwrites an agent's entry and `revoke` deletes it, so after either the old
+ * bearer is simply absent — byte-for-byte identical to one that never existed. The ONLY moment the
+ * difference is observable is the reload that removes it, which this process is already doing.
+ * Persisting it would mean a new file or a schema change (⟨q-4b9cdeab⟩'s `previous` is documented in
+ * a comment and written by NOTHING), and release A writes neither form of token. So:
+ *   · a bearer retired while this daemon was RUNNING is reported as retired;
+ *   · a bearer retired while it was DOWN reads as unknown, and that is the honest answer — this
+ *     process never saw it valid. A test asserts that limit rather than only the happy path.
+ * Hashes only: a retirement record is never a place a secret appears.
+ */
+const RETIRED_MAX = 512;
+const retiredBearers = new Map<string, RetiredBearerRecord>();
+export type RetiredBearerRecord = { agentId: string; at: number; cause: "replaced" | "revoked" };
+
+/** Record what a reload removed. `cause` is derived, not guessed: see `retirementCause`. */
+export function noteRetired(entries: RetiredHash[], after: Map<string, string> | null, now = Date.now()): void {
+  for (const { hash, agentId } of entries) {
+    retiredBearers.set(hash, { agentId, at: now, cause: retirementCause(agentId, after) });
+    // Bounded so a long-lived daemon rotating often cannot grow this without limit. Insertion order
+    // is iteration order for a Map, so the oldest record is the one that goes.
+    if (retiredBearers.size > RETIRED_MAX) {
+      const oldest = retiredBearers.keys().next();
+      if (!oldest.done) retiredBearers.delete(oldest.value);
+    }
+  }
+}
+
+/**
+ * Replaced or revoked? The agent still holding a key after the reload was ROTATED; an agent with no
+ * key left was REVOKED. Derived from the map itself rather than from which command an operator ran,
+ * because the daemon never sees the command.
+ */
+export function retirementCause(agentId: string, after: Map<string, string> | null): "replaced" | "revoked" {
+  if (!after) return "revoked";
+  for (const held of after.values()) if (held === agentId) return "replaced";
+  return "revoked";
+}
+
+/** What this process knows about a presented bearer that is no longer live, or undefined. */
+export function retiredBearerFor(bearer: string): RetiredBearerRecord | undefined {
+  return retiredBearers.get(bearerHash(bearer));
+}
+
+/** Test seam only: forget every retirement, so a case can pose an empty process memory. */
+export function clearRetiredBearers(): void {
+  retiredBearers.clear();
+}
+
 export function refreshTokenMapIfChanged(opts: { force?: boolean; now?: number } = {}): TokenMapRefresh {
   if (!tokenMapInitialized) getTokenMap();
   const { next, result } = decideTokenMapRefresh(
@@ -479,6 +558,8 @@ export function refreshTokenMapIfChanged(opts: { force?: boolean; now?: number }
     { stamp: stampOf, read: readTokenMapSync },
     opts,
   );
+  // Before the cache moves: everything the old map held and the new one does not is retired.
+  if (result.retired?.length) noteRetired(result.retired, next.map, opts.now);
   tokenMapCache = next.map;
   tokenMapStamp = next.stamp;
   tokenMapCheckedAt = next.checkedAt;
@@ -729,6 +810,70 @@ function sanitize(id: string): string {
   return id.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 
+/* ── ⟨q-524305dd⟩ ONE DELIVERER PER (SEAT, SOURCE) AT A TIME, ACROSS PROCESSES ─────────────────────
+   Two paths type a room message into a herdr pane: the SENDER's server at send time (herdr-delivery)
+   and the RECIPIENT's own tail (herdr-tail). Each read the push cursor, typed, waited seconds to
+   verify the screen, and only then advanced it; the other read the same not-yet-advanced cursor in
+   that window and typed the message again. Measured 2026-09-24: 6 of 39 room messages reached one
+   seat's pane twice, 2.7–3.5s apart. The only guard was a closure-local `inFlight` flag — per
+   PROCESS, against a race between processes.
+   So read → type → verify → advance runs under a lock BOTH paths can see: a directory lock
+   (proper-lockfile, the same one appendJsonl uses) per seat and source.
+   ⛔ A holder that DIES must not deafen the seat. The lock's mtime is refreshed while its owner's
+   event loop runs, and it is STALE after DELIVERY_LOCK_STALE_MS without a refresh, so a killed sender
+   costs a bounded stall, never a permanent one. It must outlast the slowest push: herdr's verify
+   sleeps by spinning, which blocks the refresh for the push's whole duration.
+   ⛔ A compromised lock is LOGGED, never thrown: the library's default throws asynchronously, which
+   would take the bus server down with it. */
+const envMs = (name: string, fallback: number, min: number) => { const n = Number(process.env[name]); return Number.isFinite(n) && n >= min ? Math.floor(n) : fallback; };
+export const DELIVERY_LOCK_STALE_MS = envMs("AGENT_COORD_DELIVERY_LOCK_STALE_MS", 60_000, 2_000);
+export const DELIVERY_LOCK_WAIT_MS = envMs("AGENT_COORD_DELIVERY_LOCK_WAIT_MS", 30_000, 0);
+export const DELIVERY_LOCK_DIR = path.join(ROOT, "delivery-locks");
+export const deliveryLockPath = (agentId: string, sourceKey: string) => path.join(DELIVERY_LOCK_DIR, `${sanitize(agentId)}--${sanitize(sourceKey)}`);
+export type DeliveryLockOutcome<T> = { ran: true; value: T } | { ran: false; why: string };
+
+/**
+ * Run `fn` as the only deliverer to `agentId`'s `sourceKey` ("dm" or "room:<chan>") on this bus.
+ * `wait: false` (a tail tick) answers `ran: false` at once when another deliverer holds it — the next
+ * tick re-reads the cursor. `wait: true` (the send-time push) waits up to DELIVERY_LOCK_WAIT_MS rather
+ * than skipping, because the seat may have NO tail (⟨q-cdb5b007⟩) and a skipped send-time push would
+ * then be a silent drop. The lock is released on every path out of `fn`, including a throw.
+ */
+export async function withDeliveryLock<T>(
+  agentId: string,
+  sourceKey: string,
+  fn: () => Promise<T>,
+  opts: { wait: boolean; log?: (line: string) => void },
+): Promise<DeliveryLockOutcome<T>> {
+  const target = deliveryLockPath(agentId, sourceKey);
+  // A compromise or a failed release is ALWAYS logged — to the caller's sink, or stderr when none is given.
+  // (Not an optional call: a lock event that is silently dropped is the invisible failure this lock exists to end.)
+  const log = opts.log ?? ((line: string) => console.error(line));
+  mkdirSync(DELIVERY_LOCK_DIR, { recursive: true });
+  const deadline = Date.now() + (opts.wait ? DELIVERY_LOCK_WAIT_MS : 0);
+  let release: () => Promise<void>;
+  for (;;) {
+    try {
+      release = await lockfile.lock(target, {
+        realpath: false,
+        stale: DELIVERY_LOCK_STALE_MS,
+        retries: 0,
+        onCompromised: (e: Error) => log(`[delivery-lock] ${sourceKey} for ${agentId} was COMPROMISED (${e.message}) — another deliverer may have taken it over; logged, not thrown`),
+      });
+      break;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "ELOCKED") return { ran: false, why: `delivery lock unavailable: ${(e as Error).message}` };
+      if (Date.now() >= deadline) return { ran: false, why: `another deliverer holds ${sourceKey} for ${agentId}` };
+      await new Promise((r) => setTimeout(r, 40 + Math.floor(Math.random() * 60)));
+    }
+  }
+  try {
+    return { ran: true, value: await fn() };
+  } finally {
+    try { await release(); } catch (e) { log(`[delivery-lock] release of ${sourceKey} for ${agentId} failed: ${(e as Error).message}`); }
+  }
+}
+
 export async function rewriteJsonl<T>(
   file: string,
   filter: (entry: T) => boolean

package/src/test-count-key.ts

@@ -0,0 +1,21 @@
+// ⟨q-f2cf9e0f⟩ — HOW A PASSING TEST IS ATTRIBUTED TO A FILE, in src/ so a probe can CALL it.
+//
+// `check-test-count` compares per-file pass counts against a committed record, and both the record's
+// keys and the glob's selections are paths relative to the package. The attribution key has to be
+// the SAME thing or the comparison is between two different namespaces.
+//
+// ⛔ IT WAS `test/${basename(file)}`, WHICH FLATTENS. Every test file sat directly in `test/`, so the
+// flattened key and the real one were identical and the defect was invisible — until a suite moved to
+// `test/live/`, whose passes then landed on the phantom key `test/<name>` while the real entry read
+// zero. A per-file guard that mis-keys is worse than no guard: it reports drift that is not there and
+// hides drift that is.
+//
+// Lives in src/ rather than beside the script for the reason measured in ⟨q-0c5476ec⟩: a probe in
+// dist/ importing out of scripts/ breaks any install that ships dist without scripts.
+import path from "node:path";
+
+/** The record/glob key for a test file: its path relative to the package, POSIX-separated. */
+export function testCountKey(pkgRoot: string, file: string | undefined): string {
+  if (!file) return "(unattributed)";
+  return path.relative(pkgRoot, file).split(path.sep).join("/");
+}