agent-coord-mcp 0.26.11 → 0.26.13

package/src/server.ts

@@ -9,6 +9,7 @@ import { z, type ZodRawShape } from "zod";
 import { coordAwaySchema, coordAwayTool, readAway, awayRefusal, secondCoordinatorRefusal } from "./tools/away.js";
 import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool } from "./tools/rotate.js";
 import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
+import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
 import {
   ensureDirs,
   getTokenMap,
@@ -345,7 +346,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "ping",
-    "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (fresh heartbeat or live transport), reachable (a DM pushed now would land), granular checks, and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity, but read-only — naming 'from' here never binds this session's identity.",
+    "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (live transport, or a fresh heartbeat ONLY where something writes one — never a local tmux-push transport's, whose heartbeat measures time since it joined rather than activity), reachable (a DM pushed now would land), granular checks including heartbeatValid (whether heartbeatFresh next to it is real evidence for this transport), and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity, but read-only — naming 'from' here never binds this session's identity.",
     pingSchema,
     gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
@@ -608,9 +609,9 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "coord_away",
-    "Declare the coordinator AWAY with a named duty officer, or RELEASE it. While ON, the duty officer is restricted to an ALLOWLIST (next_unblocked, claim, land, stall_check, and reporting) \u2014 an allowlist rather than a denylist, so a tool added tomorrow is refused by default instead of silently granted. Refuses ON without a dutyOfficerId (an unnamed stand-in reports the lane covered while leaving it uncovered), refuses a self-appointed officer, and refuses RELEASE by anyone but the coordinator who set it \u2014 a stand-in that can lift its own limits does not have any. While ON, a SECOND coordinator cannot join until released.",
+    "Declare that DAVID IS AWAY and the aide LEADS, or RELEASE it. (Redefined 2026-08-30; the old duty-officer meaning is RETIRED, not deprecated \u2014 one label, one meaning.) The lead DECIDES planning, priority, queue curation, roadmap, canon and releases under standing authorisation; NEVER merges, gates, or takes a code lane (enforced: `merge` and `land` are refused with their reason); and PARKS licence, funding, public-vs-private, credentials, anything altering scope or authority, and destructive machine actions \u2014 those are not the aide's to decide and an absence is not a transfer of that authority. Requires a `leadId` (an unnamed lead reports the fleet as led while leaving it unled) and a `decisionLog` path, so David returns to a diff rather than a transcript. THE PRECONDITION IS MEASURED COVERAGE, NOT A CLOCK RUN: it reads `stall_check`'s own unmeasurable list \u2014 never `stall_clock_status`'s green, which cannot express its own blindness \u2014 and REFUSES when the clock would run and see nothing, unless `acknowledgeBlindFleet:true` records that the promise is being made anyway.",
     coordAwaySchema,
-    gate("coordinatorId" as "agentId", coordAwayTool as (a: Record<string, unknown>) => Promise<unknown>),
+    gate("agentId", coordAwayTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
   addTool(
@@ -629,11 +630,18 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "subscribe",
-    "Register for a record event: a task completing, a phase completing, or a queue item closing. Events are DERIVED from the record \u2014 emitted by `land` after the DONE entry is written, and refused if the ref is not in the record \u2014 so the stream can never claim something the authoritative markdown does not. 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.",
     subscribeSchema,
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "scan_record_events",
+    "Turn a repo's COMMITTED record changes into events: new `docs/DONE.md` entries, queue items that left `docs/QUEUE.md`, and newly-ticked phase checkboxes, between the stored watermark and HEAD. The commit is the boundary \u2014 an uncommitted edit is not yet a record. A HAND-EDIT fires exactly like `land` does, which is the point: fleets merge with `gh` and edit DONE.md directly. Reports by default; `write:true` delivers and advances the watermark. Re-scanning a delivered range is safe (the idempotency key comes from the event, so it reports duplicate-suppressed), and a watermark that no longer resolves REFUSES rather than silently narrowing its window.",
+    scanRecordEventsSchema,
+    gate(null, scanRecordEventsTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   addTool(
     "unsubscribe",
     "Remove one of YOUR subscriptions. Refuses another agent's: silently dropping someone else's notification is how a miss is manufactured.",
@@ -723,6 +731,24 @@ async function main() {
     }
     const server = buildServer(boundAgent, { trackSession: true });
     const transport = new StdioServerTransport();
+    // StdioServerTransport only wires `data`/`error` on stdin — it never
+    // observes EOF. A client that ends the pipe (Claude Code's `/mcp`
+    // reconnect calls `stdin.end()` on the child) leaves this process with
+    // nothing listening for it, so it idles forever: measured as 25 live
+    // servers against 15 registered agents, one pane holding 3 generations.
+    // React to the session ending from EITHER direction — the read side
+    // closing (client done talking to us) or the write side breaking
+    // (client stopped listening, so a reply would EPIPE) — rather than
+    // waiting on the SDK client's own SIGTERM escalation to reach us.
+    const exitOnSessionEnd = (reason: string) => {
+      console.error(`[agent-coord-mcp] stdio session ended (${reason}) — exiting`);
+      process.exit(0);
+    };
+    process.stdin.on("end", () => exitOnSessionEnd("stdin end"));
+    process.stdin.on("close", () => exitOnSessionEnd("stdin close"));
+    process.stdout.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EPIPE") exitOnSessionEnd("stdout EPIPE");
+    });
     await server.connect(transport);
   }
 }
@@ -791,6 +817,58 @@ async function startHttp(port: number): Promise<void> {
   // by a *different* bearer that merely presents its id (session hijack).
   const sessionAgents = new Map<string, string | undefined>();
 
+  // Session-orphan reap (docs/DECISIONS.md ADR-015 gate #2, QUEUE.md:175 part
+  // 2). Design history, kept because the rejected shape is as load-bearing as
+  // the shipped one:
+  //
+  // `transport.onclose` — the SDK's only cleanup hook — fires exclusively from
+  // an explicit DELETE (webStandardStreamableHttp.js, "Handles DELETE requests
+  // to terminate sessions"). Measured: `Client.close()` never sends one —
+  // `StreamableHTTPClientTransport.close()` only aborts locally, and the
+  // separate `terminateSession()` method that DOES send DELETE is never
+  // called anywhere in the generic client path (shared/protocol.js). So a
+  // client that reconnects the ordinary way (close + new client, the same
+  // shape as the stdio leak fixed one level up) orphans its session here
+  // forever — confirmed live: a session answered 200 after `client.close()`.
+  //
+  // FIRST DESIGN WAS IDLE-TIMEOUT, AND IT WAS WRONG — kept as the cautionary
+  // case, not deleted: the stdio sibling of this fix (#169) shipped the same
+  // shape and was HELD after a live test proved the failure mode. Killing a
+  // session's process out from under a still-attached client produces
+  // SILENT, NON-RECOVERABLE loss — no transparent respawn, confirmed by
+  // killing this repo's own coord-mcp subprocess and watching every
+  // `mcp__agent-coord__*` tool vanish with no automatic recovery. Idle is not
+  // abandoned: an agent can sit quiet for 128 minutes while working normally.
+  // A timer cannot tell those apart; it was never going to be safe as the
+  // sole signal, on the daemon or on stdio.
+  //
+  // WHAT ACTUALLY DISTINGUISHES ABANDONED FROM QUIET: whether a NEWER session
+  // for the same bound agent already exists. If it does, the OLD session's
+  // own client already reconnected — the exact shape measured live (a fresh
+  // `client.connect()` after `client.close()`) — and closing the superseded
+  // session costs that client nothing, because it already moved on. This
+  // needs no timer and no guess: `agentSessions` tracks the current session
+  // per bound agent, and a session that stops being current is provably
+  // orphaned the instant it is superseded.
+  //
+  // Unbound (TOFU/advisory) sessions have no agent identity to key
+  // supersession on, so they get none of this — deliberately: a mechanism
+  // that cannot tell "superseded" from "just another session" must not guess.
+  const agentSessions = new Map<string, string>();
+
+  async function reapSuperseded(agentId: string, supersededId: string): Promise<void> {
+    const transport = sessions.get(supersededId);
+    if (!transport) return; // already gone
+    console.error(
+      `[agent-coord-mcp] reaping session ${supersededId} for agent '${agentId}' — superseded by a newer session`,
+    );
+    try {
+      await transport.close();
+    } catch (err) {
+      console.error(`[agent-coord-mcp] reap FAILED for session ${supersededId}:`, err);
+    }
+  }
+
   async function makeSessionTransport(boundAgent?: string): Promise<StreamableHTTPServerTransport> {
     // `let` + explicit type lets the SDK callbacks close over the binding
     // before it's assigned — they only fire after construction completes.
@@ -800,12 +878,27 @@ async function startHttp(port: number): Promise<void> {
       onsessioninitialized: (id: string) => {
         sessions.set(id, transport);
         sessionAgents.set(id, boundAgent);
+        if (boundAgent) {
+          const superseded = agentSessions.get(boundAgent);
+          agentSessions.set(boundAgent, id);
+          if (superseded && superseded !== id) {
+            reapSuperseded(boundAgent, superseded).catch((err) =>
+              console.error("[agent-coord-mcp] supersession reap threw:", err),
+            );
+          }
+        }
       },
     });
     transport.onclose = () => {
       if (transport.sessionId) {
         sessions.delete(transport.sessionId);
         sessionAgents.delete(transport.sessionId);
+        // Only clear the agent's CURRENT pointer if it still points here — a
+        // superseded session closing after its successor already claimed the
+        // slot must not erase the successor's own entry.
+        if (boundAgent && agentSessions.get(boundAgent) === transport.sessionId) {
+          agentSessions.delete(boundAgent);
+        }
       }
     };
     const server = buildServer(boundAgent);

package/src/tools/away.ts

@@ -1,41 +1,97 @@
 /*
- * `coord_away` — Phase 5 Task 4.1/4.2.
+ * `coord_away` — DAVID IS AWAY AND THE AIDE LEADS.
  *
- * WHAT THIS IS NOT: a way to hand the coordinator's judgement to someone else.
- * A duty officer keeps the lane MOVING while the coordinator is away; it does
- * not inherit the authority to decide what the lane is for. The distinction is
- * the whole point, so it is enforced as an ALLOWLIST rather than a denylist:
- * a new tool added tomorrow is refused by default, and someone must decide, in
- * writing, that a duty officer may call it.
+ * REDEFINED (David, 2026-08-30). The verb used to mean "the coordinator stepped
+ * out and a duty officer keeps its seat warm". That meaning is RETIRED, not
+ * deprecated: same skill label, one meaning. A verb with two meanings is read
+ * as whichever one the reader already had in mind, and the two differ on who
+ * holds authority — the most expensive thing to be ambiguous about.
  *
- * A denylist would have the opposite failure — every tool anyone forgets to
- * list is silently granted — which is the same shape as an empty check rollup
- * scoring green (kit#125): absence read as permission.
+ * WHAT IT NOW MEANS: David is away, and the aide LEADS in his absence. That is
+ * a grant of DECISION authority, not of execution authority, and the boundary
+ * is the feature:
  *
- * ENFORCEMENT LIVES IN `addTool`, THE SINGLE PATH EVERY TOOL IS REGISTERED
- * THROUGH, for the reason kit#125 folded the check into the merge call: a
- * guard repeated at call sites is a guard someone forgets at one call site,
- * and the forgotten one looks identical to the guarded ones from outside.
+ *   DECIDES  planning · priority · queue curation · roadmap · canon · releases
+ *            under standing publish authorisation.
+ *   NEVER    merges, gates, or takes a code lane. Unchanged by the grant — a
+ *            lead is not a second worker, and the aide's nevers are what keep
+ *            the gate non-author.
+ *   PARKS    licence · funding · public-vs-private · credentials · anything
+ *            altering scope or authority · destructive machine actions.
+ *
+ * WHY PARK RATHER THAN REFUSE-AND-FORGET: a parked decision is one David
+ * returns to. The whole point of leading in an absence is that the absence ends,
+ * and the fleet should hand back a DIFF rather than a transcript — which is why
+ * `decisionLog` is required to turn this on rather than being a nice-to-have.
+ *
+ * THE PRECONDITION IS MEASURED COVERAGE, NOT A RUN. Going away is a promise
+ * that the fleet is observed while nobody is watching, and the fleet was
+ * measured making that promise with a stall clock that had been stopped for
+ * eight hours — and then, once started, reporting `checked 3 · measurable 0`.
+ * "The clock ran" and "the fleet is observed" are different facts. So the
+ * precondition asks what the clock could actually SEE, and going away blind is
+ * a deliberate, recorded act rather than a silent default.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { ROOT } from "../store.js";
+import { stallCheckTool } from "./stall.js";
 
 const awayFile = () => path.join(ROOT, "coord-away.json");
 
 /**
- * WHAT A DUTY OFFICER MAY DO: move claimed work along and report.
+ * WHAT THE LEAD MAY NOT DO, enforced rather than trusted to a card line.
+ *
+ * ALLOWLIST FOR THE OLD MEANING, DENYLIST FOR THIS ONE — and the asymmetry is
+ * deliberate rather than a relaxation. A duty officer's grant was NARROW ("keep
+ * claimed work moving"), so absence had to mean refusal or every unlisted tool
+ * was a silent grant. A lead's grant is WIDE by design: it decides planning,
+ * priority, curation, roadmap, canon and releases, which is most of the bus. An
+ * allowlist over a wide grant would have to enumerate nearly every tool, and the
+ * one someone forgets would refuse legitimate work in the middle of an absence —
+ * failing in the direction that leaves the fleet stuck with nobody to ask.
  *
- * Deliberately absent, each for its own reason rather than by omission:
- *   `merge`          — merging is a judgement about whether work is DONE.
- *   `register`/`join` w/ coordinator role — see `secondCoordinatorRefusal`.
- *   grow-fleet verbs — a stand-in does not get to change the fleet's shape.
- *   CANON writes     — canon outlives the absence that created the stand-in.
+ * What is refused is small, closed, and named for its reason: the aide's
+ * `never merges / never gates` rule. That rule does not widen when David leaves;
+ * it is load-bearing precisely because the gate must stay non-author.
+ */
+export const LEAD_REFUSED: Record<string, string> = {
+  merge: "merging is the gate acting. The aide never gates, and leading in David's absence does not change who may — a lead that merges is an author gating its own plan.",
+  land: "`land` writes docs/DONE.md, which is the coordinator's file. Leading does not transfer file ownership; ask the coordinator to record it.",
+};
+
+/**
+ * Decisions that WAIT for David. Not refused because they are dangerous to
+ * execute — refused because they are not the aide's to make, and an absence is
+ * not a transfer of that authority.
  */
-export const DUTY_OFFICER_ALLOWLIST = ["next_unblocked", "claim", "land", "stall_check", "stall_clock_status", "post_status", "send_message", "read_messages", "status", "heartbeat", "list_work"] as const;
+export const PARKED_CATEGORIES = [
+  "licence",
+  "funding",
+  "public-vs-private",
+  "credentials",
+  "anything altering scope or authority",
+  "destructive machine actions",
+] as const;
 
-export type AwayState = { on: boolean; project: string; coordinatorId: string; dutyOfficerId: string; until?: string; at: string };
+export type AwayCoverage = { checked: number; measurable: number; blind: string[]; at: string };
+
+export type AwayState = {
+  on: boolean;
+  project: string;
+  /** Who is away. The verb is about DAVID's absence now. */
+  away: string;
+  /** The agent leading in that absence — the aide. */
+  leadId: string;
+  until?: string;
+  at: string;
+  /** Where decisions taken during the absence are written, so David returns to a diff. */
+  decisionLog: string;
+  coverage: AwayCoverage;
+  /** True when this was turned on knowing the fleet is unobserved. */
+  blindAcknowledged?: boolean;
+};
 
 export function readAway(): Record<string, AwayState> {
   const f = awayFile();
@@ -53,69 +109,179 @@ function writeAway(state: Record<string, AwayState>): void {
 }
 
 /**
- * The refusal a duty officer gets, or null if the call is allowed.
+ * The refusal the LEAD gets, or null if the call is allowed.
  *
- * Only the DUTY OFFICER is constrained. Everyone else's lane is unchanged:
- * `coord-away` is not a freeze on the project, and a worker whose tools stop
- * working because the coordinator stepped out would simply stop calling them.
+ * Only the lead is constrained, and only on the two verbs above. Everyone
+ * else's lane is untouched: `coord_away` is not a freeze on the project, and a
+ * worker whose tools stopped working because David went out would simply stop
+ * calling them.
  */
 export function awayRefusal(state: Record<string, AwayState>, agentId: string | undefined, tool: string): string | null {
   if (!agentId) return null;
-  const held = Object.values(state).find((s) => s.on && s.dutyOfficerId === agentId);
+  const held = Object.values(state).find((s) => s.on && s.leadId === agentId);
   if (!held) return null;
-  if ((DUTY_OFFICER_ALLOWLIST as readonly string[]).includes(tool)) return null;
-  return `'${tool}' is not on the duty-officer allowlist. You are standing in for '${held.coordinatorId}' on '${held.project}' while coord-away is ON: a duty officer keeps the lane MOVING and does not inherit the authority to decide what it is for. Allowed: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. If this genuinely needs doing, it needs ${held.coordinatorId} back or David — not a wider allowlist added in the moment.`;
+  const why = LEAD_REFUSED[tool];
+  if (!why) return null;
+  return (
+    `'${tool}' is refused while you LEAD on '${held.project}' in David's absence: ${why} ` +
+    `Leading grants DECISION authority — planning, priority, curation, roadmap, canon, releases — not execution authority. ` +
+    `If this genuinely needs doing, it needs the coordinator, or David back. Record it in ${held.decisionLog} either way.`
+  );
 }
 
 /**
- * 4.2 — a SECOND coordinator may not join while the first is away.
+ * RETIRED WITH THE OLD MEANING. Kept as a no-op so the call site in
+ * `registerTool` keeps compiling and the retirement is visible where the guard
+ * used to be, rather than as an absence someone re-derives later.
+ *
+ * Under the old meaning the coordinator was the one away, so a second
+ * coordinator joining was a fleet-shape change made behind its back. Under this
+ * one the coordinator is present and working, and blocking a second coordinator
+ * while DAVID is out would refuse a legitimate handoff at exactly the moment
+ * nobody can approve it.
  *
- * Not a lock for its own sake: two coordinators is the condition under which
- * two GOs can be issued for one lane, and the absent one cannot see the other
- * arrive. The duty officer exists precisely so the seat is not empty, so a
- * second claimant is a fleet-shape change, which is the category `coord_away`
- * refuses by construction.
+ * RECORDED GAP, deliberately not solved here: retiring the duty-officer meaning
+ * leaves COORDINATOR absence uncovered. If the coordinator goes down while David
+ * is away, nothing covers the seat. That is a decision, not an oversight — it is
+ * named so the next reader finds a choice rather than a hole.
  */
-export function secondCoordinatorRefusal(state: Record<string, AwayState>, agentId: string, roleId: string | undefined): string | null {
-  if (roleId !== "coordinator") return null;
-  const held = Object.values(state).find((s) => s.on && s.coordinatorId !== agentId);
-  if (!held) return null;
-  return `coord-away is HELD on '${held.project}' by '${held.coordinatorId}' (duty officer '${held.dutyOfficerId}'). A second coordinator cannot join until it is RELEASED — two coordinators is the condition under which one lane gets two GOs, and the absent one cannot see the second arrive.`;
+export function secondCoordinatorRefusal(
+  _state: Record<string, AwayState>,
+  _agentId: string,
+  _roleId: string | undefined,
+): string | null {
+  return null;
 }
 
 export const coordAwaySchema = {
   project: z.string().min(1),
   on: z.boolean(),
-  coordinatorId: z.string().min(1),
-  dutyOfficerId: z.string().optional(),
+  /** The agent leading in David's absence — the aide. */
+  leadId: z.string().optional(),
+  /** Repo-relative path where decisions taken during the absence are written. */
+  decisionLog: z.string().optional(),
   until: z.string().optional(),
+  /** Repo to measure stall coverage against. */
+  repo: z.string().optional(),
+  /** Turn it on knowing the fleet is unobserved. Recorded in the state. */
+  acknowledgeBlindFleet: z.boolean().optional(),
+  /** Who is calling — the lead may turn it on and release it. */
+  agentId: z.string().optional(),
 };
 
-export async function coordAwayTool(args: { project: string; on: boolean; coordinatorId: string; dutyOfficerId?: string; until?: string }) {
+async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
+  if (!repo) return null;
+  try {
+    const r = (await stallCheckTool({ repo })) as unknown as {
+      ok?: boolean; checked?: number; measurable?: number; blind?: string[];
+    };
+    if (!r?.ok) return null;
+    return { checked: r.checked ?? 0, measurable: r.measurable ?? 0, blind: r.blind ?? [], at: new Date().toISOString() };
+  } catch {
+    return null;
+  }
+}
+
+export async function coordAwayTool(args: {
+  project: string;
+  on: boolean;
+  leadId?: string;
+  decisionLog?: string;
+  until?: string;
+  repo?: string;
+  acknowledgeBlindFleet?: boolean;
+  agentId?: string;
+}) {
   const state = readAway();
   const prior = state[args.project];
 
   if (args.on) {
-    // A STAND-IN WITH NO NAME IS AN EMPTY SEAT DESCRIBED AS COVERED, which is
-    // strictly worse than a seat everyone can see is empty.
-    if (!args.dutyOfficerId) return { ok: false as const, error: `coord-away ON requires a dutyOfficerId. Turning it on without naming a stand-in reports the lane as covered while leaving it uncovered.` };
-    if (args.dutyOfficerId === args.coordinatorId) return { ok: false as const, error: `'${args.coordinatorId}' cannot be its own duty officer.` };
-    if (prior?.on && prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away is already HELD on '${args.project}' by '${prior.coordinatorId}'. Release it first.` };
-    state[args.project] = { on: true, project: args.project, coordinatorId: args.coordinatorId, dutyOfficerId: args.dutyOfficerId, until: args.until, at: new Date().toISOString() };
+    // A LEAD WITH NO NAME IS AN ABSENCE DESCRIBED AS COVERED, which is strictly
+    // worse than an absence everyone can see is uncovered.
+    if (!args.leadId) {
+      return { ok: false as const, error: `coord-away ON requires a leadId — the agent leading in David's absence. Turning it on without naming one reports the fleet as led while leaving it unled.` };
+    }
+    if (!args.decisionLog) {
+      return {
+        ok: false as const,
+        error:
+          `coord-away ON requires a decisionLog path. The point of leading through an absence is that the absence ENDS: ` +
+          `David should return to a diff he can read, not a transcript he has to reconstruct. A log promised at the start ` +
+          `and written at the end is a log nobody wrote.`,
+      };
+    }
+    if (prior?.on) {
+      return { ok: false as const, error: `coord-away is already ON for '${args.project}' — '${prior.leadId}' leads since ${prior.at}. Release it before re-arming.` };
+    }
+
+    // THE PRECONDITION: what could the clock actually SEE?
+    const coverage = await measureCoverage(args.repo);
+    if (!coverage) {
+      return {
+        ok: false as const,
+        error:
+          `cannot measure stall coverage for '${args.project}'${args.repo ? "" : " — pass 'repo'"}. ` +
+          `Going away is a promise that the fleet is watched while nobody is watching, and an UNMEASURED promise ` +
+          `is the one this verb exists to stop making. Fix the measurement, or pass acknowledgeBlindFleet:true to ` +
+          `record that the promise is being made anyway.`,
+      };
+    }
+    // `checked > 0` MATTERS: an empty board is an IDLE fleet, not a blind one.
+    // Without it, arming while nothing is in flight refuses with "the clock
+    // covers 0 of 0" — a refusal that reads as a fleet nobody can see when in
+    // fact there is nothing to see, and the only way past it would be to
+    // acknowledge a blindness that does not exist.
+    if (coverage.checked > 0 && coverage.measurable === 0 && !args.acknowledgeBlindFleet) {
+      return {
+        ok: false as const,
+        error:
+          `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.checked} in-flight row(s). ` +
+          `It would RUN and see nothing${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}. ` +
+          `"The clock ran" and "the fleet is observed" are different facts, and this verb must not treat the first as the second. ` +
+          `The usual cause is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref: a path resolves for ` +
+          `git and measures the wrong thing, so the check reports it unmeasurable rather than guessing. Fix those cells and ` +
+          `coverage returns. If you mean to go anyway, pass acknowledgeBlindFleet:true — it is recorded in the state and in the announcement.`,
+      };
+    }
+
+    state[args.project] = {
+      on: true,
+      project: args.project,
+      away: "david",
+      leadId: args.leadId,
+      until: args.until,
+      at: new Date().toISOString(),
+      decisionLog: args.decisionLog,
+      coverage,
+      ...(coverage.checked > 0 && coverage.measurable === 0 ? { blindAcknowledged: true } : {}),
+    };
     writeAway(state);
     return {
       ok: true as const,
       state: state[args.project],
-      allowlist: DUTY_OFFICER_ALLOWLIST,
-      announce: `AGENT_ACTION: coord-away ON — '${args.coordinatorId}' away${args.until ? ` until ${args.until}` : ""}; '${args.dutyOfficerId}' is duty officer, limited to: ${DUTY_OFFICER_ALLOWLIST.join(", ")}. A second coordinator cannot join until released.`,
+      refused: LEAD_REFUSED,
+      parked: PARKED_CATEGORIES,
+      announce:
+        `AGENT_ACTION: coord-away ON — David is away${args.until ? ` until ${args.until}` : ""}; '${args.leadId}' LEADS. ` +
+        `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
+        `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
+        `Decisions logged to ${args.decisionLog}. ` +
+        `Stall coverage ${coverage.measurable}/${coverage.checked}${coverage.checked > 0 && coverage.measurable === 0 ? " — ACKNOWLEDGED BLIND: the clock runs and sees nothing" : ""}.`,
     };
   }
 
-  // RELEASE IS THE COORDINATOR'S. A duty officer releasing its own limits is
-  // the limit not existing — the one call it must not be able to make.
   if (!prior?.on) return { ok: false as const, error: `coord-away is not on for '${args.project}' — nothing to release.` };
-  if (prior.coordinatorId !== args.coordinatorId) return { ok: false as const, error: `coord-away on '${args.project}' is held by '${prior.coordinatorId}' and only they can release it. A stand-in that can lift its own limits does not have any.` };
+  // RELEASE IS OBSERVING THAT DAVID IS BACK, not lifting a limit on yourself —
+  // which is why the lead may do it and a duty officer could not. The parked
+  // decisions are NOT unparked by it: they were never the lead's to make, and
+  // release does not retroactively authorise one.
   state[args.project] = { ...prior, on: false, at: new Date().toISOString() };
   writeAway(state);
-  return { ok: true as const, state: state[args.project], announce: `AGENT_ACTION: coord-away RELEASED on '${args.project}' — '${prior.coordinatorId}' is back; '${prior.dutyOfficerId}' stands down.` };
+  return {
+    ok: true as const,
+    state: state[args.project],
+    announce:
+      `AGENT_ACTION: coord-away RELEASED on '${args.project}' — David is back; '${prior.leadId}' stands down as lead. ` +
+      `Anything parked during the absence is still parked: release does not authorise it. Decisions taken: ${prior.decisionLog}.`,
+  };
 }

package/src/tools/event-kinds.ts

@@ -0,0 +1,60 @@
+/*
+ * The subscribable kind vocabulary — a LEAF module, importing nothing.
+ *
+ * It lives alone because `events.ts` and `record-events.ts` both need it and
+ * import each other: with the registry inside `record-events.ts`, loading that
+ * module FIRST threw `Cannot access 'EVENT_KIND_IDS' before initialization`,
+ * since `events.ts` reads it at module scope while `record-events.ts` is still
+ * evaluating. It worked only because `tools/index.ts` happens to export
+ * `events.js` first — a load-ORDER dependency, invisible until something
+ * imports the module directly, which is exactly what a consumer or a test does.
+ *
+ * A cycle that works by luck is not a working cycle.
+ */
+/**
+ * The kind vocabulary lives HERE, beside the emitters, and `events.ts` imports
+ * it. That direction is deliberate: it is what makes the enum impossible to
+ * widen without adding an emitter in the same file.
+ */
+export type SubKind = keyof typeof EVENT_KINDS;
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
+
+/*
+ * THE KIND REGISTRY IS THE SINGLE SOURCE, AND THAT IS TASK 9.2.
+ *
+ * `SubKind` used to be a hand-written union next to a hand-written zod enum next
+ * to an emitter that covered one of the four. Nothing connected them, so a kind
+ * could be offered for subscription while nothing could ever emit it — and
+ * `list_subscriptions` would report its permanent `never evaluated` forever,
+ * honestly and uselessly.
+ *
+ * Now the union, the wire enum, and the emitter set are all derived from THIS
+ * object. A kind cannot be offered without an emitter because the enum is
+ * generated from the emitters; `test/record-events.test.mjs` closes the other
+ * half by asserting each kind actually fires. Unsatisfiable BY CONSTRUCTION,
+ * rather than by a reviewer noticing.
+ */
+export const EVENT_KINDS = {
+  item: {
+    record: "docs/QUEUE.md + docs/DONE.md",
+    what: "a queue item closed — it left QUEUE.md and a DONE.md entry appeared in the same commit",
+    targetIs: "the queue item id",
+  },
+  pr: {
+    record: "docs/DONE.md",
+    what: "a PR recorded in the completion log",
+    targetIs: "the PR ref, e.g. owner/repo#163",
+  },
+  task: {
+    record: "docs/phases/**/PHASE*_TASKS.md",
+    what: "a phase task checkbox newly ticked",
+    targetIs: "the task key, e.g. 5:12.1",
+  },
+  phase: {
+    record: "docs/phases/**/PHASE*_TASKS.md",
+    what: "the last open checkbox in a phase document ticked",
+    targetIs: "the phase number, e.g. 5",
+  },
+} as const;
+
+export const EVENT_KIND_IDS = Object.keys(EVENT_KINDS) as [SubKind, ...SubKind[]];

package/src/tools/events.ts

@@ -13,10 +13,16 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { ROOT } from "../store.js";
+import { EVENT_KINDS, EVENT_KIND_IDS, type RecordEvent, type SubKind } from "./event-kinds.js";
 
 const subsFile = () => path.join(ROOT, "subscriptions.json");
 
-export type SubKind = "task" | "phase" | "item" | "pr";
+// Re-exported so every existing importer keeps its import path. The vocabulary
+// itself is defined beside the emitters (record-events.ts) — Task 9.2: a kind
+// that can be subscribed to but never emitted is unsatisfiable BY CONSTRUCTION
+// only if the enum cannot be widened without an emitter.
+export { EVENT_KINDS, EVENT_KIND_IDS };
+export type { RecordEvent, SubKind };
 export type Subscription = {
   id: string;
   agentId: string;
@@ -77,8 +83,6 @@ export function subscriptionHealth(s: Subscription): { level: "ok" | "error"; de
 export const eventKey = (kind: SubKind, target: string, ref: string): string =>
   createHash("sha256").update(`${kind}:${target}:${ref}`).digest("hex").slice(0, 16);
 
-export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
-
 /**
  * 6.2 — EVENTS ARE DERIVED FROM THE RECORD, NEVER PARALLEL TO IT.
  *
@@ -139,7 +143,7 @@ export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): {
 
 export const subscribeSchema = {
   agentId: z.string().min(1),
-  kind: z.enum(["task", "phase", "item", "pr"]),
+  kind: z.enum(EVENT_KIND_IDS),
   target: z.string().min(1),
 };
 

package/src/tools/index.ts

@@ -9,3 +9,5 @@ export * from "./work.js";
 export * from "./records.js";
 export * from "./worktrees.js";
 export * from "./stall.js";
+export * from "./events.js";
+export * from "./record-events.js";