agent-coord-mcp 0.26.5 → 0.26.7

package/scripts/coord-attention-clock.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/*
+ * Emit on MERGEABLE-AND-UNATTENDED.
+ *
+ * Two mergeable, CI-green PRs sat 17 hours; two more sat 40 minutes and 1h48 on
+ * the day the coordinator said it was checking for that. Nothing in the room
+ * said so — a worker went looking. This is the mechanism that was missing.
+ *
+ * A TIMER, NOT A TRIGGER, for the reason the stall clock is: a mechanism
+ * without a schedule measures inbound traffic rather than elapsed time, and
+ * cannot fire during exactly the quiet it exists to cover.
+ *
+ * Named unit: com.davidbalzan.coord-attention-clock (see --install).
+ *
+ * UNKNOWN IS NOT UNATTENDED. `mergeable` is UNKNOWN for a while after every
+ * push and an empty rollup is ambiguous; both are reported as unknown, never as
+ * an alert. Inventing an alert from a question GitHub has not answered is the
+ * fabrication class this fleet has spent three days removing.
+ *
+ * REPORTED ONCE, not every tick: delivery goes through the same subscription
+ * machinery as record events, so the idempotency key suppresses a repeat. A DM
+ * every 30 minutes about the same PR trains its own dismissal.
+ */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const argv = Object.fromEntries(
+  process.argv.slice(2).flatMap((a) => {
+    const m = /^--([^=]+)(?:=(.*))?$/.exec(a);
+    return m ? [[m[1], m[2] ?? true]] : [];
+  }),
+);
+const here = path.dirname(fileURLToPath(import.meta.url));
+const dist = path.join(here, "..", "dist");
+const LABEL = "com.davidbalzan.coord-attention-clock";
+
+if (argv.install) {
+  const repo = String(argv.repo ?? process.cwd());
+  const to = String(argv.to ?? "<coordinator-agent-id>");
+  const every = Number(argv.every ?? 15);
+  const self = path.join(here, "coord-attention-clock.mjs");
+  console.log(`# macOS launchd — Label: ${LABEL}
+#   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${LABEL}.plist
+<?xml version="1.0" encoding="UTF-8"?>
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>${process.execPath}</string><string>${self}</string>
+    <string>--repo=${repo}</string><string>--to=${to}</string>
+  </array>
+  <key>StartInterval</key><integer>${every * 60}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardErrorPath</key><string>${path.join(homedir(), "agent-coord", "logs", "attention-clock.err")}</string>
+</dict></plist>
+
+# Linux cron:
+# */${every} * * * * ${process.execPath} ${self} --repo=${repo} --to=${to}
+`);
+  process.exit(0);
+}
+
+const repo = String(argv.repo ?? process.cwd());
+const to = argv.to ? String(argv.to) : null;
+const from = String(argv.from ?? "coord-attention-clock");
+const quietMinutes = Number(argv["quiet-minutes"] ?? 20);
+
+const { partition } = await import(path.join(dist, "tools/attention.js"));
+const { readSubs, evaluate, commitEvaluation } = await import(path.join(dist, "tools/events.js"));
+const { sendMessageTool } = await import(path.join(dist, "tools/messaging.js"));
+
+let prs;
+try {
+  const out = execFileSync(
+    "gh",
+    ["pr", "list", "--state", "open", "--json", "number,state,mergeable,updatedAt,statusCheckRollup"],
+    { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+  );
+  prs = JSON.parse(out).map((p) => ({ ...p, checks: p.statusCheckRollup ?? [] }));
+} catch (e) {
+  // NOT FETCHED IS NOT NOTHING-TO-REPORT. A silent failure here is exactly the
+  // quiet that let the PRs sit.
+  console.error(`[attention-clock] FAILED to list PRs: ${(e && e.message) || e}`);
+  process.exit(1);
+}
+
+const now = Date.now();
+const { unattended, unknown, attended } = partition(prs, now, quietMinutes * 60_000);
+
+let delivered = 0;
+if (to) {
+  const subs = readSubs();
+  let next = subs;
+  const fresh = [];
+  for (const u of unattended) {
+    const ev = { kind: "pr", target: "mergeable-unattended", ref: `#${u.pr.number}`, summary: u.why };
+    const r = evaluate(next, ev, now);
+    next = r.subs;
+    if (r.deliveries.some((d) => d.status === "delivered")) fresh.push(u);
+  }
+  commitEvaluation(next);
+  if (fresh.length) {
+    await sendMessageTool({
+      from,
+      to,
+      text:
+        `AGENT_ACTION: ${fresh.length} PR(s) MERGEABLE AND UNATTENDED.\n` +
+        fresh.map((u) => `- ${u.why}`).join("\n") +
+        `\n\nScheduled check (${LABEL}), not a person. Verify before merging: this reports GATE-READINESS, never that the change is correct.`,
+    });
+    delivered = fresh.length;
+  }
+}
+
+// The null result every run: a check that only speaks when it fires cannot be
+// told from a broken one. `unknown` is printed separately from `attended`
+// because collapsing them is the defect this script refuses to commit.
+console.log(
+  `[attention-clock] ${prs.length} open · unattended ${unattended.length} (DM'd ${delivered}) · unknown ${unknown.length} · attended ${attended}` +
+    (unknown.length ? `\n  unknown:\n${unknown.map((u) => `    ${u.why}`).join("\n")}` : ""),
+);

package/scripts/coord-stall-clock.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/*
+ * THE CLOCK. Runs `stall_check` on a schedule and DMs the duty officer on HIT.
+ *
+ * WHY A SCHEDULER AND NOT AN AGENT LOOP: a mechanism without a schedule is
+ * REACTIVE, and its null reports measure inbound traffic rather than elapsed
+ * time. console-worker-1's standing trigger ran zero times in seventeen hours
+ * because it only fired when a message woke it — so it could not run during
+ * exactly the period it existed to cover, a fleet gone quiet. `wait_for_message`
+ * is disqualified for the same reason (Task 3.3).
+ *
+ * THE UNIT IS NAMED, because "standing" without a named scheduler is a habit:
+ *   macOS   launchd  com.davidbalzan.coord-stall-clock   (see --install)
+ *   Linux   cron     the line --install prints
+ *
+ * WHAT IT MEASURES WHEN NOBODY IS WATCHING: that is the whole point, and it is
+ * why this is a timer rather than a trigger.
+ *
+ * MISS IS SILENT TO THE DUTY OFFICER AND NEVER SILENT TO THE RECORD. A DM every
+ * 30 minutes trains its own dismissal; a missing run mark makes a dead clock
+ * look like a healthy fleet. `stall_check` writes the mark itself; this script
+ * additionally records FAILURES, without which a clock that throws every time
+ * leaves no marks at all and is identical on disk to one never installed.
+ *
+ * It does NOT speak MCP: `stallCheckTool` is a plain function over
+ * ~/agent-coord and the repo's board, so a timer needs no server and no
+ * transport. One less thing that can be up while the thing it watches is down.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const argv = Object.fromEntries(
+  process.argv.slice(2).flatMap((a) => {
+    const m = /^--([^=]+)(?:=(.*))?$/.exec(a);
+    return m ? [[m[1], m[2] ?? true]] : [];
+  }),
+);
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const dist = path.join(here, "..", "dist");
+
+const LABEL = "com.davidbalzan.coord-stall-clock";
+
+if (argv.install) {
+  const repo = String(argv.repo ?? process.cwd());
+  const duty = String(argv.duty ?? "<duty-officer-agent-id>");
+  const every = Number(argv.every ?? 30);
+  const self = path.join(here, "coord-stall-clock.mjs");
+  const node = process.execPath;
+  console.log(`# macOS — launchd. Label: ${LABEL}
+# Write to ~/Library/LaunchAgents/${LABEL}.plist, then:
+#   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/${LABEL}.plist
+<?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>${LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>${node}</string><string>${self}</string>
+    <string>--repo=${repo}</string><string>--duty=${duty}</string>
+  </array>
+  <key>StartInterval</key><integer>${every * 60}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardErrorPath</key><string>${path.join(homedir(), "agent-coord", "logs", "stall-clock.err")}</string>
+</dict></plist>
+
+# Linux — cron:
+# */${every} * * * * ${node} ${self} --repo=${repo} --duty=${duty}
+`);
+  process.exit(0);
+}
+
+const repo = String(argv.repo ?? process.cwd());
+const duty = argv.duty ? String(argv.duty) : null;
+const from = String(argv.from ?? "coord-stall-clock");
+const stallMinutes = argv["stall-minutes"] ? Number(argv["stall-minutes"]) : undefined;
+
+const { stallCheckTool, markRunFailure } = await import(path.join(dist, "tools/stall.js"));
+const { sendMessageTool } = await import(path.join(dist, "tools/messaging.js"));
+
+try {
+  const r = await stallCheckTool({ repo, ...(stallMinutes ? { stallMinutes } : {}) });
+
+  // `ok:false` is a FAILURE, not a quiet fleet — e.g. no board at that path.
+  // Recorded, or the next `stall_clock_status` reads a stopped clock as absent
+  // rather than broken.
+  if (!r.ok) {
+    markRunFailure(r.error ?? "stall_check returned ok:false with no reason");
+    console.error(`[stall-clock] FAILED: ${r.error}`);
+    process.exit(1);
+  }
+
+  if (r.hits.length && duty) {
+    const lines = r.hits.map((h) =>
+      h.kind === "no-heartbeat"
+        ? `- ${h.agentId}: no heartbeat for ${h.minutes}m (${h.stream})`
+        : `- ${h.agentId}: no commits on ${h.branch} for ${h.minutes}m`,
+    );
+    await sendMessageTool({
+      from,
+      to: duty,
+      text: `AGENT_ACTION: stall_check HIT — ${r.hits.length} of ${r.checked} in-flight row(s) stalled.\n${lines.join("\n")}\n\nThis is a scheduled check (${LABEL}), not a person watching. Verify before acting: a stall is a claim about the BOARD, not about the agent.`,
+    });
+  }
+
+  // Null result to stdout every run: the log is the record a human reads, and a
+  // trigger that only speaks when it fires cannot be told from a broken one.
+  const um = r.unmeasurable?.length ? `, ${r.unmeasurable.length} unmeasurable` : "";
+  console.log(
+    r.hits.length
+      ? `[stall-clock] HIT ${r.hits.length}/${r.checked}${um}${duty ? ` — DM sent to ${duty}` : " — NO DUTY OFFICER SET, no DM"}`
+      : `[stall-clock] MISS 0/${r.checked}${um} — no DM, run recorded`,
+  );
+} catch (e) {
+  // THE CLAUSE MOST EASILY SKIPPED. A clock that throws every time leaves no
+  // marks, which on disk is identical to a clock that was never installed.
+  const reason = (e && e.message) || String(e);
+  try {
+    markRunFailure(reason);
+  } catch {
+    /* if even the mark cannot be written, stderr is all that is left */
+  }
+  console.error(`[stall-clock] FAILED: ${reason}`);
+  process.exit(1);
+}

package/src/prefix.ts

@@ -0,0 +1,72 @@
+/*
+ * WHERE WILL A NEW GLOBAL INSTALL LAND, AND IS IT WHERE THE FLEET LOADS FROM?
+ *
+ * These are two different questions and neither answers the other. The
+ * `server-build-drift` check names which copy is RUNNING; this names where the
+ * NEXT copy will be written. A run of `npm i -g agent-coord-mcp` that prints
+ * "added 1 package" is not evidence it landed anywhere that runs.
+ *
+ * MEASURED ON THIS BOX, 2026-08-28 — the divergence is not hypothetical:
+ *   npm prefix -g          -> .../node/v22.22.2
+ *   every live fleet server-> .../node/v22.21.1/lib/node_modules/agent-coord-mcp
+ * Three prefixes exist here (two nvm, one /opt/homebrew), `npm prefix -g` is
+ * PATH-dependent, and nvm switches it per shell. So the install target and the
+ * load target had silently diverged, and a successful install would have
+ * updated a copy nothing loads. That gap cost the fleet a day.
+ */
+import path from "node:path";
+
+/**
+ * The global root a module path sits under, or null if it is not in one.
+ * `/p/lib/node_modules/agent-coord-mcp/dist` -> `/p`
+ */
+export function prefixOf(modulePath: string | undefined): string | null {
+  if (!modulePath) return null;
+  // Split on the LAST occurrence: a global prefix can itself live under a path
+  // containing `node_modules`, and taking the first match would name an
+  // ancestor that installs nothing.
+  const marker = `${path.sep}lib${path.sep}node_modules${path.sep}`;
+  const i = modulePath.lastIndexOf(marker);
+  if (i === -1) return null;
+  return modulePath.slice(0, i);
+}
+
+export type PrefixVerdict =
+  | { level: "ok"; detail: string }
+  | { level: "warn"; detail: string }
+  | { level: "error"; detail: string };
+
+/**
+ * `loadPrefix` is where THIS server was loaded from; `installPrefix` is what
+ * `npm prefix -g` answered, and `npmPath` is which npm answered it — because a
+ * prefix without the binary that reported it cannot be reproduced by anyone.
+ */
+export function prefixVerdict(loadPrefix: string | null, installPrefix: string | null, npmPath?: string): PrefixVerdict {
+  const via = npmPath ? ` (asked: ${npmPath})` : "";
+
+  // NOT DETERMINED IS NOT MATCHING. Both unknown branches are warnings that say
+  // what could not be established, never an "ok" over an unasked question.
+  // NOT APPLICABLE IS NOT THE SAME AS UNCHECKED, and conflating them is how a
+  // check earns its way into being ignored. A dev checkout has no load prefix
+  // BY CONSTRUCTION: this process is not the copy the fleet loads, so there is
+  // no divergence for it to have. Warning on every dev run would fire on every
+  // test run and every local session — noise, which is what a denylist does.
+  //
+  // The question is still ASKED where it can be answered: a session running
+  // from a global install has a load prefix, and that is where the fleet lives.
+  if (!loadPrefix)
+    return { level: "ok", detail: `not applicable: this server runs from a dev checkout, not a global install${via}, so it is not the copy the fleet loads and has no prefix to diverge from. Run \`doctor\` in an installed session to compare install target against load target.` };
+  if (!installPrefix)
+    return { level: "warn", detail: `could not determine the global install prefix${via} — \`npm prefix -g\` gave no answer, so where a new copy would land is UNKNOWN. Running from ${loadPrefix}.` };
+
+  if (path.resolve(loadPrefix) === path.resolve(installPrefix))
+    return { level: "ok", detail: `a global install would land where this server loads from (${loadPrefix})${via}` };
+
+  return {
+    level: "error",
+    detail:
+      `INSTALL PREFIX AND LOAD PREFIX DIVERGE. A global install from this shell writes to ${installPrefix}${via}, but this server is running from ${loadPrefix}. ` +
+      `A successful "added 1 package" would update a copy nothing loads, and every check that reads a VERSION would keep reporting the old one truthfully. ` +
+      `Install with an explicit prefix (\`npm i -g --prefix ${loadPrefix} <pkg>\`) or switch node/nvm to the version owning ${loadPrefix} before installing.`,
+  };
+}

package/src/server.ts

@@ -6,6 +6,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { unlinkSync, writeFileSync } from "node:fs";
 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 {
   ensureDirs,
   getTokenMap,
@@ -79,6 +82,24 @@ import {
   listScopesTool,
   importWorkSchema,
   importWorkTool,
+  stallCheckSchema,
+  stallCheckTool,
+  setHaltSchema,
+  setHaltTool,
+  lastRanSchema,
+  stallClockStatusTool,
+  ensureWorktreeSchema,
+  ensureWorktreeTool,
+  refreshWorktreesSchema,
+  refreshWorktreesTool,
+  claimSchema,
+  claimTool,
+  landSchema,
+  landTool,
+  mergeSchema,
+  mergeTool,
+  nextUnblockedSchema,
+  nextUnblockedTool,
   listWorkSchema,
   listWorkTool,
   exportWorkSchema,
@@ -250,9 +271,18 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     inputSchema: ZodRawShape,
     cb: (args: Record<string, unknown>) => Promise<ReturnType<typeof jsonResult>>,
   ) => {
-    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) =>
-      cb((args ?? {}) as Record<string, unknown>),
-    );
+    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) => {
+      const a = (args ?? {}) as Record<string, unknown>;
+      // DUTY-OFFICER ALLOWLIST, ENFORCED IN THE ONE PATH EVERY TOOL IS
+      // REGISTERED THROUGH. Placed here rather than in `gate` because `gate`
+      // does not know the tool's NAME, and because a guard applied per call
+      // site is a guard someone forgets at one call site — where the omission
+      // looks identical to the guarded ones from outside (kit#125).
+      const caller = bound ?? (typeof a["agentId"] === "string" ? (a["agentId"] as string) : typeof a["from"] === "string" ? (a["from"] as string) : undefined);
+      const refusal = awayRefusal(readAway(), caller, name);
+      if (refusal) throw new Error(refusal);
+      return cb(a);
+    });
   };
 
   addTool(
@@ -513,6 +543,111 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate(null, listWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "stall_check",
+    "The stall predicate over the board and the bus: a 🚧 row 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.",
+    stallCheckSchema,
+    gate(null, stallCheckTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "stall_clock_status",
+    "Is the stall clock alive? Reports when stall_check last ran, how many runs, and how many were misses — so 'no alerts' is distinguishable from 'nothing ran'. Never having run is an ERROR, not a quiet fleet.",
+    lastRanSchema,
+    gate(null, stallClockStatusTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "set_halt",
+    "Set or clear a NAMED halt. While set, `claim` and `next_unblocked` refuse. The reason is required because a halt blocks every lane in the fleet: it must name a board cutover, a cited BLOCKER: or a documented red pipeline — 'production feels down' is not a halt.",
+    setHaltSchema,
+    gate(null, setHaltTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "ensure_worktree",
+    "Create or reuse an isolated git worktree for an agent, cut from origin/<base> (never a local branch of the same name, which is whatever the last person left there). Refuses to hand back the PRIMARY checkout as a slice tree — that is the path everyone already has, so it is the one two agents end up editing at once. Idempotent: an existing tree is reported as found, and if it sits on a different branch that is said rather than re-pointed.",
+    ensureWorktreeSchema,
+    gate(null, ensureWorktreeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "refresh_worktrees",
+    "Fast-forward IDLE worktrees onto origin/<base>. Never --force and never a mid-slice tree: dirty or holding commits the base does not is REFUSED per tree and named, because staleness is visible in a diff and a clobbered work-in-progress is not. Reports by default; pass apply:true to move them.",
+    refreshWorktreesSchema,
+    gate(null, refreshWorktreesTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "next_unblocked",
+    "The next queue item to work: re-reads docs/QUEUE.md via the seam, orders P1>P2>P3 with document order breaking ties, and SKIPS a blocked item rather than stalling the lane on a reorder (returning the board hunk to record the skip). Also reports items NOTHING WAITS ON as their own axis: an item that blocks nothing announces nothing when it stalls, so its absence is silent and needs an explicit check at a stage boundary.",
+    nextUnblockedSchema,
+    gate(null, nextUnblockedTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "claim",
+    "Bind a queue item to an agent and produce the 🚧 board row. With no itemId it takes next_unblocked. WARNS LOUDLY while `ensure_worktree` (Phase 5 Task 1) does not exist: the claim binds the item and the row only, and creating an isolated worktree at origin/<base> is still yours. The warning is conditional on that verb's absence, so it stops once Task 1 lands.",
+    claimSchema,
+    gate(null, claimTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "land",
+    "Record a merged PR: refuses without a cited PR number, and refuses unless the PR is on the TARGET TIP (origin/<base>) rather than a merge base — an item merged after your branch was cut is missing from the base too, so the base cannot answer 'what does the thing I am merging into have that I do not?'. Closes the queue item STATUS ONLY (priority and body bytes unchanged), proposes the DONE entry, and reports by default: pass write:true to apply.",
+    landSchema,
+    gate(null, landTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "merge",
+    "Merge a PR ONLY as the consequence of its check verdict: reads the status rollup and merges in the same call, so there is no ordering in which the check runs and the merge ignores it. Refuses on any failing check, on any check not yet terminal, on a CONFLICTING base, and on ZERO checks \u2014 no checks is not passing checks, an empty rollup has zero failures and evidences nothing. Every return carries the POPULATION it judged. Reports by default; pass write:true to merge.",
+    mergeSchema,
+    gate(null, mergeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  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.",
+    coordAwaySchema,
+    gate("coordinatorId" as "agentId", coordAwayTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "rotate",
+    "Build a handover-to-self packet from LIVE state (git + gh), never chat memory \u2014 memory is the one source that cannot be re-derived after the reset it is meant to survive. REFUSES while the tree is dirty: uncommitted work is the one thing a packet cannot carry, and after /clear nothing can discover it existed. Jobs are an allowlist (reseed-only | phase-boundary); 'archive-done' is deliberately absent. Reports by default; write:true persists the packet.",
+    rotateSchema,
+    gate("agentId", rotateTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "rotate_reconcile",
+    "FIRST ACT AFTER A RESEED. Re-checks every packet claim against live state and REFUSES to report ready on any divergence \u2014 a PR that merged during the reset is the dangerous direction, because the agent resumes a branch already in main and every next step is coherent and wrong. 'missionHint' is reported as UNVERIFIABLE rather than counted as reconciled.",
+    rotateReconcileSchema,
+    gate("agentId", rotateReconcileTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  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.",
+    subscribeSchema,
+    gate("agentId", subscribeTool 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.",
+    unsubscribeSchema,
+    gate("agentId", unsubscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
+  addTool(
+    "list_subscriptions",
+    "List subscriptions with their health. A subscription NEVER EVALUATED is an ERROR, not a quiet zero \u2014 'no events yet' and 'never ran' are the same output and only one is healthy. Carries its population, because 'no subscriptions' and 'none listed for you' are different claims.",
+    listSubscriptionsSchema,
+    gate(null, listSubscriptionsTool as (a: Record<string, unknown>) => Promise<unknown>),
+  );
+
   addTool(
     "export_work",
     "Render a project's work documents back out of the store, reproducing the pinned glyph contract exactly (ref after the last ' \u2014 ', date after a trailing ' \u00b7 '). Reports by default; pass write:true to rewrite the files. Refuses to export from an empty store rather than blanking a document. Refuses write:true when that write would emit a new 5-col lanes-v0 table (parse-only; write grammar is workstreams.v1). Any declared Task 4 write scope is REPORTED alongside the write, never enforced.",

package/src/tools/attention.ts

@@ -0,0 +1,91 @@
+/*
+ * Emit on the state that has twice cost hours: a PR that is MERGEABLE and
+ * UNATTENDED.
+ *
+ * Two mergeable, CI-green PRs sat 17 hours; two more sat 40 minutes and 1h48
+ * on the day the coordinator said it was checking for exactly that. Nothing in
+ * the room said so — a worker went looking and found it. There is no mechanism
+ * that reports "these PRs are mergeable and nobody is acting".
+ *
+ * 6.2 APPLIES HERE TOO: the event is DERIVED from observable state, never a
+ * parallel claim. Everything below is computed from what GitHub actually
+ * reports, and anything it has not answered yet is `unknown`.
+ */
+import { normalizeChecks } from "./records.js";
+
+export type PrFactsForAttention = {
+  number: number;
+  state: string;
+  mergeable: string;
+  updatedAt: string;
+  checks: unknown[];
+  repo?: string;
+};
+
+export type Attention =
+  | { state: "unattended"; why: string }
+  | { state: "unknown"; why: string }
+  | { state: "attended"; why: string };
+
+/**
+ * UNKNOWN IS NOT UNATTENDED, and this is the clause the coordinator and I have
+ * both been bitten by today.
+ *
+ * `mergeable` is `UNKNOWN` for a while after every push — GitHub computes it
+ * asynchronously — and an empty check rollup is ambiguous between "not yet" and
+ * "never will be". Reading either as "nobody is acting" invents an alert out of
+ * a question GitHub has not answered, which is the fabrication class this fleet
+ * has spent three days removing.
+ */
+export function classifyPr(pr: PrFactsForAttention, nowMs: number, quietMs: number): Attention {
+  if (pr.state !== "OPEN") return { state: "attended", why: `#${pr.number} is ${pr.state}` };
+
+  if (!pr.mergeable || pr.mergeable === "UNKNOWN")
+    return {
+      state: "unknown",
+      why: `#${pr.number}: GitHub has not computed mergeability yet (frequently the case right after a push). UNKNOWN is not unattended — reporting it would invent an alert from an unanswered question.`,
+    };
+
+  if (pr.mergeable === "CONFLICTING")
+    return { state: "attended", why: `#${pr.number} is CONFLICTING — it needs its author, not a gate` };
+
+  const checks = normalizeChecks(pr.checks ?? []);
+  if (checks.length === 0)
+    return {
+      state: "unknown",
+      why: `#${pr.number} reports ZERO checks — ambiguous between "not started" and "never will". No checks is not passing checks, and it is not unattended either.`,
+    };
+
+  const pending = checks.filter((c) => c.verdict === "pending");
+  if (pending.length)
+    return { state: "unknown", why: `#${pr.number}: ${pending.length} check(s) still running — not yet a gate's turn` };
+
+  const failed = checks.filter((c) => c.verdict === "fail");
+  if (failed.length)
+    return { state: "attended", why: `#${pr.number} has failing checks (${failed.map((c) => c.name).join(", ")}) — the author's move, not the gate's` };
+
+  // Quiet is measured from the PR's own last update. A PR touched a minute ago
+  // is not unattended; its author may still be pushing.
+  const quietFor = nowMs - Date.parse(pr.updatedAt);
+  if (!Number.isFinite(quietFor))
+    return { state: "unknown", why: `#${pr.number}: unreadable updatedAt '${pr.updatedAt}' — cannot say how long it has waited` };
+  if (quietFor < quietMs)
+    return { state: "attended", why: `#${pr.number} was updated ${Math.round(quietFor / 60000)}m ago — still moving` };
+
+  return {
+    state: "unattended",
+    why: `#${pr.number} is MERGEABLE, all ${checks.length} check(s) pass, and nothing has touched it for ${Math.round(quietFor / 60000)}m`,
+  };
+}
+
+/** The three states are distinct on purpose; a caller must not collapse them. */
+export function partition(prs: PrFactsForAttention[], nowMs: number, quietMs: number) {
+  const out = { unattended: [] as { pr: PrFactsForAttention; why: string }[], unknown: [] as { pr: PrFactsForAttention; why: string }[], attended: 0 };
+  for (const pr of prs) {
+    const c = classifyPr(pr, nowMs, quietMs);
+    if (c.state === "unattended") out.unattended.push({ pr, why: c.why });
+    else if (c.state === "unknown") out.unknown.push({ pr, why: c.why });
+    else out.attended++;
+  }
+  return out;
+}