agent-coord-mcp 0.26.6 → 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/server.ts

@@ -8,6 +8,7 @@ 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,
@@ -626,6 +627,27 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     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;
+}

package/src/tools/events.ts

@@ -0,0 +1,199 @@
+/*
+ * Event subscriptions — stop relying on someone CHOOSING to tell you.
+ *
+ * The bus is almost entirely direct messaging: an agent learns something
+ * happened because another agent decided to say so. Every miss this week was a
+ * missing NOTIFICATION rather than a missing capability — two mergeable PRs sat
+ * 17 hours because nobody told the coordinator to gate, the console's trigger
+ * ran zero times because nothing woke it, and `stall_check` runs only when a
+ * human types it.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+const subsFile = () => path.join(ROOT, "subscriptions.json");
+
+export type SubKind = "task" | "phase" | "item" | "pr";
+export type Subscription = {
+  id: string;
+  agentId: string;
+  kind: SubKind;
+  target: string;
+  createdAt: number;
+  /** null until this subscription has been EVALUATED at least once. */
+  lastEvaluatedAt: number | null;
+  lastEventAt: number | null;
+  /** Idempotency keys already delivered, for 6.4. */
+  delivered: string[];
+};
+
+export function readSubs(): Subscription[] {
+  const f = subsFile();
+  if (!existsSync(f)) return [];
+  try {
+    return (JSON.parse(readFileSync(f, "utf8")).subscriptions ?? []) as Subscription[];
+  } catch {
+    return [];
+  }
+}
+
+function writeSubs(subs: Subscription[]): void {
+  mkdirSync(ROOT, { recursive: true });
+  writeFileSync(subsFile(), `${JSON.stringify({ subscriptions: subs }, null, 2)}\n`);
+}
+
+/**
+ * 6.3 — A SUBSCRIPTION THAT NEVER FIRES MUST BE DISTINGUISHABLE FROM ONE NEVER
+ * REGISTERED, so never-evaluated is an ERROR rather than a quiet zero.
+ *
+ * We hit the absence of this rule twice in two days: the console's standing
+ * trigger and `stall_check`'s clock both looked healthy while never running. A
+ * subscription with no last-evaluated mark has produced no evidence of
+ * anything, and "no events" is the same output a broken subscription gives.
+ */
+export function subscriptionHealth(s: Subscription): { level: "ok" | "error"; detail: string } {
+  if (s.lastEvaluatedAt === null)
+    return {
+      level: "error",
+      detail: `never evaluated — this subscription has produced no evidence it is wired to anything. "No events yet" and "never ran" are the same output, and only one of them is healthy.`,
+    };
+  return {
+    level: "ok",
+    detail: s.lastEventAt
+      ? `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, last event ${new Date(s.lastEventAt).toISOString()}`
+      : `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, no events yet — evaluated and quiet, which is different from never run`,
+  };
+}
+
+/**
+ * 6.4 — DELIVERY IS AT-LEAST-ONCE BY DESIGN. Safe for a reader, DOUBLE
+ * EXECUTION for an executor: a callback that triggers work must carry a key, or
+ * the same merge lands twice. The key is derived from the EVENT, never from the
+ * delivery attempt, so a retry produces the same key.
+ */
+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.
+ *
+ * Enforced here rather than promised in a comment: the event's `ref` must
+ * already be present in the record document before anything is emitted. An
+ * event stream that can say "task X complete" while DONE.md does not is a
+ * second source of truth, and record-vs-state divergence is the defect this
+ * fleet hit most this week. ADR-003 keeps markdown authoritative, and this must
+ * not quietly reopen it.
+ *
+ * So the ordering is not a convention: emission READS the record, and an event
+ * whose cause is not in the record cannot be emitted at all.
+ */
+export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true } | { ok: false; error: string } {
+  if (!ev.ref) return { ok: false, error: `event for ${ev.kind} ${ev.target} carries no ref — nothing ties it to a record entry` };
+  if (!String(recordText).includes(ev.ref))
+    return {
+      ok: false,
+      error:
+        `refusing to emit ${ev.kind} ${ev.target}: its ref ${ev.ref} is NOT in the record. ` +
+        `An event that exists without the record change that caused it is a second source of truth — ` +
+        `the stream would claim something the authoritative document does not.`,
+    };
+  return { ok: true };
+}
+
+/** Subscriptions matching an event. Exact target match; no wildcards yet. */
+export const matching = (subs: Subscription[], ev: RecordEvent): Subscription[] =>
+  subs.filter((s) => s.kind === ev.kind && s.target === ev.target);
+
+export type Delivery = { subscriptionId: string; agentId: string; key: string; status: "delivered" | "duplicate-suppressed" };
+
+/**
+ * Evaluate every subscription against one event and return what to deliver.
+ *
+ * EVALUATION IS RECORDED EVEN WHEN NOTHING MATCHES — that is 6.3's whole point.
+ * A subscription only learns it is alive by being evaluated, so the mark is
+ * written for every subscription of that kind, not only the ones that fired.
+ */
+export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): { subs: Subscription[]; deliveries: Delivery[] } {
+  const key = eventKey(ev.kind, ev.target, ev.ref);
+  const deliveries: Delivery[] = [];
+  const next = subs.map((s) => {
+    if (s.kind !== ev.kind) return s;
+    const evaluated = { ...s, lastEvaluatedAt: now };
+    if (s.target !== ev.target) return evaluated;
+    if (s.delivered.includes(key)) {
+      deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "duplicate-suppressed" });
+      return evaluated;
+    }
+    deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "delivered" });
+    return { ...evaluated, lastEventAt: now, delivered: [...s.delivered, key].slice(-200) };
+  });
+  return { subs: next, deliveries };
+}
+
+/* ── verbs ─────────────────────────────────────────────────────────────────── */
+
+export const subscribeSchema = {
+  agentId: z.string().min(1),
+  kind: z.enum(["task", "phase", "item", "pr"]),
+  target: z.string().min(1),
+};
+
+export async function subscribeTool(args: { agentId: string; kind: SubKind; target: string }) {
+  const subs = readSubs();
+  const dupe = subs.find((s) => s.agentId === args.agentId && s.kind === args.kind && s.target === args.target);
+  if (dupe) return { ok: true as const, subscription: dupe, note: "already subscribed — returning the existing registration rather than a second one" };
+  const sub: Subscription = {
+    id: randomUUID(),
+    agentId: args.agentId,
+    kind: args.kind,
+    target: args.target,
+    createdAt: Date.now(),
+    lastEvaluatedAt: null,
+    lastEventAt: null,
+    delivered: [],
+  };
+  writeSubs([...subs, sub]);
+  return { ok: true as const, subscription: sub, health: subscriptionHealth(sub) };
+}
+
+export const unsubscribeSchema = { agentId: z.string().min(1), id: z.string().min(1) };
+
+export async function unsubscribeTool(args: { agentId: string; id: string }) {
+  const subs = readSubs();
+  const sub = subs.find((s) => s.id === args.id);
+  if (!sub) return { ok: false as const, error: `no subscription '${args.id}'` };
+  // Another agent's subscription is not yours to remove: silently dropping
+  // someone else's notification is how a miss is manufactured.
+  if (sub.agentId !== args.agentId) return { ok: false as const, error: `subscription '${args.id}' belongs to '${sub.agentId}', not '${args.agentId}'` };
+  writeSubs(subs.filter((s) => s.id !== args.id));
+  return { ok: true as const, removed: sub };
+}
+
+export const listSubscriptionsSchema = { agentId: z.string().optional() };
+
+export async function listSubscriptionsTool(args: { agentId?: string }) {
+  const all = readSubs();
+  const subs = args.agentId ? all.filter((s) => s.agentId === args.agentId) : all;
+  const rows = subs.map((s) => ({ ...s, health: subscriptionHealth(s) }));
+  const neverEvaluated = rows.filter((r) => r.health.level === "error");
+  return {
+    ok: neverEvaluated.length === 0,
+    // Population beside the verdict, always: "no subscriptions" and "none
+    // listed for you" are different claims.
+    population: { listed: rows.length, total: all.length },
+    subscriptions: rows,
+    ...(neverEvaluated.length
+      ? { error: `${neverEvaluated.length} of ${rows.length} subscription(s) have NEVER been evaluated — they have produced no evidence of being wired to anything.` }
+      : {}),
+  };
+}
+
+/** Persist an evaluation. Callers do this after a record write, never before. */
+export function commitEvaluation(next: Subscription[]): void {
+  writeSubs(next);
+}