agent-coord-mcp 0.26.12 → 0.26.13

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,7 +13,7 @@ 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 "./record-events.js";
+import { EVENT_KINDS, EVENT_KIND_IDS, type RecordEvent, type SubKind } from "./event-kinds.js";
 
 const subsFile = () => path.join(ROOT, "subscriptions.json");
 

package/src/tools/record-events.ts

@@ -26,53 +26,10 @@
  */
 import { execFileSync } from "node:child_process";
 import { newlyTickedInDiff, parseWorkDoc, queueItemsOf, doneEntriesOf } from "@davidbalzan/groundwork-seam";
-/**
- * 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 };
+import { EVENT_KINDS, type RecordEvent, type SubKind } from "./event-kinds.js";
+export { EVENT_KINDS, EVENT_KIND_IDS } from "./event-kinds.js";
+export type { RecordEvent, SubKind } from "./event-kinds.js";
 
-/*
- * 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[]];
 
 /**
  * One pass over the diff → per-file added and removed lines.
@@ -122,6 +79,39 @@ const linesWhere = (byFile: ReturnType<typeof diffByFile>, match: (p: string) =>
  */
 const PR_REF = /^(?:[\w.-]+\/[\w.-]+#\d+|#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)$/;
 
+
+/**
+ * EVERY pr ref in a citation field, not "is the whole field one ref".
+ *
+ * MEASURED, and it is the mirror image of the garbage-ref defect: an anchored
+ * whole-field match rejects `owner/repo#170, #173` — a perfectly good citation
+ * that happens to name TWO PRs. A real closure was reported unattributed for
+ * exactly this, and a pair of PRs is the repo's normal house style for work
+ * that landed across two.
+ *
+ * Tightening to reject prose was right. Rejecting a real citation because it
+ * cites more than one thing was not, and from inside a function that only asks
+ * "does the field EQUAL a ref" the two failures are indistinguishable.
+ *
+ * A BARE `#N` IS EXPANDED against a qualified ref in the same field: in
+ * `owner/repo#170, #173` the second plainly means the same repository, and
+ * emitting a bare `#173` would be an under-qualified target that no
+ * subscription written against `owner/repo#173` could ever match.
+ */
+export function prRefsIn(field: string | undefined): string[] {
+  const text = String(field ?? "");
+  const out: string[] = [];
+  for (const m of text.matchAll(/(?:[\w.-]+\/[\w.-]+#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)/g)) out.push(m[0]);
+  const owner = out[0]?.match(/^([\w.-]+\/[\w.-]+)#/)?.[1];
+  for (const m of text.matchAll(/(?:^|[\s,\u00b7;])#(\d+)\b/g)) {
+    const ref = owner ? `${owner}#${m[1]}` : `#${m[1]}`;
+    if (!out.includes(ref)) out.push(ref);
+  }
+  return out;
+}
+
+/** A citation that closes an item without naming a PR — `owner/repo@sha`. */
+const COMMIT_REF = /@[0-9a-f]{7,40}\b/;
 /** Queue and done text, compared for the pairing below. */
 const norm = (s: string) => String(s).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
 
@@ -149,9 +139,12 @@ export function eventsFromCommittedChange(
   const newEntries = doneEntriesOf(parseWorkDoc(`## Done\n${addedDone.join("\n")}\n`)) as Array<{ ref?: string; text?: string }>;
 
   for (const entry of newEntries) {
-    const ref = entry.ref?.trim();
-    if (!ref || !PR_REF.test(ref)) continue;
-    events.push({ kind: "pr", target: ref, ref, summary: entry.text?.slice(0, 120) || ref });
+    // ONE EVENT PER PR NAMED. An entry closing work that spanned two PRs should
+    // wake a subscriber to either; collapsing to the first makes the second
+    // silently unwatchable.
+    for (const ref of prRefsIn(entry.ref)) {
+      events.push({ kind: "pr", target: ref, ref, summary: entry.text?.slice(0, 120) || ref });
+    }
   }
 
   // ── item: a queue item that closed ────────────────────────────────────────
@@ -170,13 +163,17 @@ export function eventsFromCommittedChange(
   const removedQueue = linesWhere(byFile, isQueue, "removed");
   const removedItems = (queueItemsOf(parseWorkDoc(`## Queue\n${removedQueue.join("\n")}\n`)) as Array<{ id?: string; text?: string }>)
     .filter((i) => i.id);
-  const prEntries = newEntries.filter((e) => e.ref && PR_REF.test(e.ref.trim()));
+  // An entry qualifies to CLOSE an item if it cites anything resolvable — a PR,
+  // or an `@sha` commit. `land` requires a PR by rule; the scan reads what the
+  // record actually says, and a commit-cited entry is still the record stating
+  // that the item closed.
+  const citedEntries = newEntries.filter((e) => prRefsIn(e.ref).length > 0 || COMMIT_REF.test(e.ref ?? ""));
   const unattributed: string[] = [];
 
   for (const item of removedItems) {
     const itemText = norm(item.text ?? "");
     let entry = itemText
-      ? prEntries.find((e) => {
+      ? citedEntries.find((e) => {
           const t = norm(e.text ?? "");
           return t && (t === itemText || t.startsWith(itemText) || itemText.startsWith(t));
         })
@@ -184,12 +181,19 @@ export function eventsFromCommittedChange(
     // The unambiguous-commit case: one out, one in. This is the shape the fleet
     // actually commits ("close its queue item"), and it is the case the aide's
     // dead `item` subscriptions need.
-    if (!entry && removedItems.length === 1 && prEntries.length === 1) entry = prEntries[0];
+    if (!entry && removedItems.length === 1 && citedEntries.length === 1) entry = citedEntries[0];
     if (!entry) {
       unattributed.push(item.id!);
       continue;
     }
-    events.push({ kind: "item", target: item.id!, ref: entry.ref!.trim(), summary: entry.text?.slice(0, 120) ?? item.id! });
+    // The FIRST pr ref is the item's, falling back to the commit citation: an
+    // item closes once, so it gets one ref, and it is the one a reader follows.
+    const ref = prRefsIn(entry.ref)[0] ?? entry.ref?.trim();
+    if (!ref) {
+      unattributed.push(item.id!);
+      continue;
+    }
+    events.push({ kind: "item", target: item.id!, ref, summary: entry.text?.slice(0, 120) ?? item.id! });
   }
   if (unattributed.length) unattributedItems.push(...unattributed);
 

package/src/tools/registry.ts

@@ -363,8 +363,17 @@ export async function listAgentsTool() {
     const { lastHeartbeat, ...rest } = a;
     const heartbeatFields = transport
       ? {
+          // NOT "refreshed BY this call" — that write was removed in #137
+          // precisely because it stamped every OTHER fleet's agents too
+          // (agents.json is shared, list_agents takes no project argument).
+          // Measured after the removal (Task 13.5): calling list_agents and
+          // re-reading agents.json directly leaves lastHeartbeat UNCHANGED.
+          // The field is omitted because the value is STALE-BY-DESIGN for a
+          // live-transport agent, not because this call would overwrite it —
+          // an explanation that outlived the code it explained is the same
+          // carrier-gap shape as a stated cause nobody re-checked.
           heartbeatSource:
-            "omitted — this agent has a live transport, so its heartbeat is refreshed BY this call and would report the caller's own timestamp. Liveness is `online`/`transport`; for per-agent freshness read from server state, use `ping`.",
+            "omitted — a live-transport agent's raw lastHeartbeat measures time since it last JOINED, not activity (nothing else writes it for a local transport; Task 13.3/13.4). Liveness is `online`/`transport`; for per-agent freshness read from server state, use `ping`.",
         }
       : { lastHeartbeat, secondsSinceHeartbeat: Math.floor((now - lastHeartbeat) / 1000) };
     return {