agent-coord-mcp 0.26.13 → 0.26.15

package/src/capabilities.ts

@@ -0,0 +1,188 @@
+/*
+ * Phase 5.1 Task 11 — CLOSE THE LOOP: answer a capability question by
+ * EXERCISING the capability, in the process that would serve it.
+ *
+ * 11.1: NO TIMESTAMP ON THIS BOX CAN ANSWER A CAPABILITY QUESTION. Every
+ * artefact people reach for is a proxy that fails differently:
+ *
+ *   an mtime          tracks WRITES. A reinstall of byte-identical code moves
+ *                     it, and an edit that never got built does not.
+ *   serverBuildMtime  is stamped at ATTACH, so it tells you when a transport
+ *                     started, not what the running process contains.
+ *   a version string  is a LABEL someone typed into package.json. Measured
+ *                     today: a tarball published as 0.5.23 contained a change
+ *                     the version numbering said it could not, and the number
+ *                     was believed over the artefact for an hour.
+ *   `npm view`        answers from a cache, and told this fleet the wrong
+ *                     published version twice in one morning.
+ *
+ * Each is honest about something and dishonest about capability, and the
+ * failure is always the same shape: an ANSWER ABOUT A LABEL read as an answer
+ * about behaviour.
+ *
+ * 11.2: A RELEASE IS NOT DELIVERED UNTIL A SERVER THAT RESTARTED ANSWERS.
+ * `merged · published · installed · restarted · observed` — five states, and
+ * the last two are the ones that keep being skipped. A probe run INSIDE the
+ * server process is the only artefact that speaks for the loaded code: it
+ * cannot be satisfied by a file that exists, a version that matches, or a
+ * package that installed, because it calls the code and reports what happened.
+ *
+ * WHY A PROBE MAY NEVER READ A VERSION: if a probe branched on a version
+ * string it would inherit that string's dishonesty, and a fleet would then
+ * have a capability check that passes on a restarted-but-not-upgraded server.
+ * Probes call behaviour. The version travels beside the answer as CONTEXT and
+ * is labelled as such.
+ */
+import { prRefsIn } from "./tools/record-events.js";
+import { EVENT_KIND_IDS } from "./tools/event-kinds.js";
+import { suggestRecordType, typedRecordMode } from "./typed-records.js";
+import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
+import { recordAuthorityFor } from "./roles.js";
+import { subscriptionHealth } from "./tools/events.js";
+
+export type ProbeResult = {
+  id: string;
+  /** The release the behaviour arrived in — reported, never TESTED against. */
+  since: string;
+  present: boolean;
+  /** What was actually called and what came back. The evidence, not a claim. */
+  evidence: string;
+};
+
+type Probe = { id: string; since: string; run: () => { present: boolean; evidence: string } };
+
+/**
+ * Each probe calls a behaviour that did not exist before its release and
+ * reports what it observed. A probe that could pass without the code being
+ * loaded is not a probe — it is a restatement of the version.
+ */
+const PROBES: Probe[] = [
+  {
+    id: "typed-records-obligatory",
+    since: "0.26.10",
+    run: () => {
+      const s = suggestRecordType("DONE: shipped it", []);
+      const mode = typedRecordMode();
+      return {
+        present: s.type === "done" && (mode === "warn" || mode === "refuse"),
+        evidence: `suggestRecordType("DONE: …") -> '${s.type}', policy mode '${mode}'`,
+      };
+    },
+  },
+  {
+    id: "record-events-all-kinds",
+    since: "0.26.12",
+    run: () => {
+      const kinds = [...EVENT_KIND_IDS].sort();
+      const present = ["item", "phase", "pr", "task"].every((k) => kinds.includes(k as never));
+      return { present, evidence: `subscribable kinds: ${kinds.join(", ")}` };
+    },
+  },
+  {
+    id: "multi-pr-citation",
+    since: "0.26.14",
+    run: () => {
+      const refs = prRefsIn("owner/repo#170, #173");
+      return {
+        present: refs.length === 2 && refs[1] === "owner/repo#173",
+        evidence: `prRefsIn("owner/repo#170, #173") -> [${refs.join(", ")}]`,
+      };
+    },
+  },
+  {
+    id: "away-means-david-away",
+    since: "0.26.13",
+    run: () => {
+      const present = "merge" in LEAD_REFUSED && PARKED_CATEGORIES.includes("licence" as never);
+      return {
+        present,
+        evidence: `coord_away refuses [${Object.keys(LEAD_REFUSED).join(", ")}] for the lead; parks ${PARKED_CATEGORIES.length} categories`,
+      };
+    },
+  },
+  {
+    id: "subscription-scanned-vs-evaluated",
+    since: "0.26.15",
+    run: () => {
+      // The capability is that "the machinery ran" and "your kind fired" are
+      // separable. Probed by asking for the state that used to be reported as
+      // broken: scanned, never evaluated — a healthy idle watch.
+      const base = { id: "p", agentId: "p", kind: "item", target: "t", createdAt: 0, lastEvaluatedAt: null, lastEventAt: null, delivered: [] } as never;
+      const quiet = subscriptionHealth({ ...(base as object), lastScannedAt: Date.now() } as never);
+      const unscanned = subscriptionHealth({ ...(base as object), lastScannedAt: null } as never);
+      return {
+        present: quiet.level === "ok" && unscanned.level === "error",
+        evidence: `scanned+quiet -> '${quiet.level}', never-scanned -> '${unscanned.level}'`,
+      };
+    },
+  },
+  {
+    id: "record-authority",
+    since: "0.24.0",
+    run: () => {
+      const worker = recordAuthorityFor({ roleId: "worker" });
+      return {
+        present: worker.mayNotEmit.includes("verdict"),
+        evidence: `a worker mayNotEmit: [${worker.mayNotEmit.join(", ")}]`,
+      };
+    },
+  },
+];
+
+export type CapabilityReport = {
+  /**
+   * WHICH PROCESS ANSWERED. Not evidence of anything — context, so a reader can
+   * tell two servers apart when their answers disagree. Deliberately beside the
+   * probe results rather than above them: the temptation this whole verb exists
+   * to remove is reading the identity INSTEAD of the answers.
+   */
+  answeredBy: { pid: number; startedAtIso: string; module: string; versionLabel: string };
+  probes: ProbeResult[];
+  missing: string[];
+  ok: boolean;
+  note: string;
+};
+
+export function probeCapabilities(context: { module: string; versionLabel: string }): CapabilityReport {
+  const probes: ProbeResult[] = PROBES.map((p) => {
+    try {
+      const r = p.run();
+      return { id: p.id, since: p.since, present: r.present, evidence: r.evidence };
+    } catch (e) {
+      // A THROWN PROBE IS AN ABSENT CAPABILITY, NOT A BROKEN CHECK. Older code
+      // that lacks the symbol throws exactly here, and reporting that as an
+      // error rather than an absence would make the common case look like a
+      // malfunction.
+      return { id: p.id, since: p.since, present: false, evidence: `probe threw: ${(e as Error).message}` };
+    }
+  });
+  const missing = probes.filter((p) => !p.present).map((p) => p.id);
+  return {
+    answeredBy: {
+      pid: process.pid,
+      startedAtIso: new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString(),
+      module: context.module,
+      versionLabel: context.versionLabel,
+    },
+    probes,
+    missing,
+    ok: missing.length === 0,
+    note:
+      "Every line above was produced by CALLING the code in this process. `versionLabel` is a label someone typed " +
+      "into package.json and is context, never evidence — a published tarball has already been observed carrying a " +
+      "change its version said it could not. THIS ANSWER IS ABOUT ONE PROCESS: a release is delivered when every " +
+      "live agent's OWN server answers, which is the fifth state (merged · published · installed · restarted · observed). " +
+      "A server that has not restarted answers honestly about the old code it is still running.",
+  };
+}
+
+/* ── the verb ──────────────────────────────────────────────────────────────── */
+
+import { resolveServerIdentity } from "./server-identity.js";
+
+export const capabilitiesSchema = {} as const;
+
+export async function capabilitiesTool() {
+  const id = resolveServerIdentity();
+  return probeCapabilities({ module: id.path, versionLabel: id.version });
+}

package/src/server-identity.ts

@@ -0,0 +1,83 @@
+/*
+ * WHICH SERVER PACKAGE IS RUNNING — a LEAF module, importing nothing from
+ * `tools/`.
+ *
+ * It lived in `transport.ts`, and `capabilities.ts` imported it from there. The
+ * moment `status` needs to REPORT capabilities, that becomes
+ * transport -> capabilities -> transport: a cycle, and the same one Task 9
+ * produced when the kind registry sat inside `record-events.ts`. That one only
+ * worked because `tools/index.ts` happened to import in the surviving order —
+ * a load-ORDER dependency, invisible until something imported a module
+ * directly, which is what a consumer or a test does.
+ *
+ * A cycle that works by luck is not a working cycle, so the shared fact moves
+ * out rather than the edge being added on top of it.
+ *
+ * NOTE WHAT THIS REPORTS AND WHAT IT DOES NOT. `version` is the label in the
+ * package.json this process loaded from — CONTEXT for a reader, never evidence
+ * of a capability. A published tarball has already been observed carrying a
+ * change its version said it could not. Capability questions are answered by
+ * `capabilities`, which CALLS the code.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isGitRepo } from "./tools/scopes.js";
+
+/** Running server package + optional git identity. `fromDir` is a test seam. */
+export function resolveServerIdentity(fromDir?: string): {
+  path: string;
+  version: string;
+  branch?: string;
+  sha?: string;
+} {
+  const start = fromDir ?? path.dirname(fileURLToPath(import.meta.url));
+  let dir = start;
+  let pkgFile: string | undefined;
+  for (let i = 0; i < 8; i++) {
+    const candidate = path.join(dir, "package.json");
+    if (existsSync(candidate)) {
+      pkgFile = candidate;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const pkgPath = pkgFile ?? path.resolve(start, "..", "..", "package.json");
+  const pkgDir = path.dirname(pkgPath);
+  let version = "unknown";
+  try {
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+    if (typeof raw.version === "string" && raw.version) version = raw.version;
+  } catch {
+    /* leave unknown — never invent a version */
+  }
+
+  const out: { path: string; version: string; branch?: string; sha?: string } = {
+    path: pkgDir,
+    version,
+  };
+
+  dir = pkgDir;
+  let gitRoot: string | undefined;
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(path.join(dir, ".git"))) {
+      gitRoot = dir;
+      break;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (gitRoot && isGitRepo(gitRoot)) {
+    const branch = spawnSync("git", ["-C", gitRoot, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    const sha = spawnSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const b = branch.status === 0 ? String(branch.stdout).trim() : "";
+    const s = sha.status === 0 ? String(sha.stdout).trim() : "";
+    if (b) out.branch = b;
+    if (s) out.sha = s;
+  }
+  return out;
+}

package/src/server.ts

@@ -10,6 +10,7 @@ import { coordAwaySchema, coordAwayTool, readAway, awayRefusal, secondCoordinato
 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 { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
 import {
   ensureDirs,
   getTokenMap,
@@ -539,7 +540,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "list_work",
-    "Query a project's work state as records instead of parsing markdown: open queue items (filter by priority), done entries with their ref and date as separate fields, the board's lane rows, and facts. Falls back to reading the documents directly when nothing has been imported, so it works with no store at all.",
+    "A re-parsing VIEW over a project's work state, not an index: it re-reads the documents (or the last import_work snapshot, reported as source:\"store\" vs \"markdown\") rather than answering from a maintained store, so treat repeated calls as costing what a fresh parse costs. Queue items come back as IDENTITY ONLY — id, priority, a bounded headline (truncated:true when cut, never silently), blockedBy — never the full body; pass id back on a second call to fetch one item's or one DONE entry's record whole. Done entries, board lane rows, and facts are returned in full. Filter queue by priority; falls back to reading the documents directly when nothing has been imported, so it works with no store at all.",
     listWorkSchema,
     gate(null, listWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -581,7 +582,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   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.",
+    "The next queue item a WORKER can claim: 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 skips — as its own reported axis, `notClaimable`, never silently — canon prose (`[SWEEP:canon]`/`[SWEEP:canon.N]`) that the aide/coordinator author directly and no worker takes as code work. 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>),
   );
@@ -635,6 +636,13 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "capabilities",
+    "What THIS SERVER PROCESS can actually do, answered by CALLING each capability rather than by reading a version, an mtime, or a file. No timestamp on the box can answer a capability question: an mtime tracks writes (a reinstall of identical bytes moves it), `serverBuildMtime` is stamped at attach, and a version is a label someone typed — a published tarball has been observed carrying a change its version said it could not. Each probe reports the call it made and what came back, so an absent capability reads as an absence rather than an error. THE ANSWER IS ABOUT ONE PROCESS: a release is delivered only when every live agent's OWN server answers, which is the fifth state (merged \u00b7 published \u00b7 installed \u00b7 restarted \u00b7 observed). A server that has not restarted answers honestly about the old code it still runs.",
+    capabilitiesSchema,
+    gate(null, capabilitiesTool as () => 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.",

package/src/tools/events.ts

@@ -29,8 +29,26 @@ export type Subscription = {
   kind: SubKind;
   target: string;
   createdAt: number;
-  /** null until this subscription has been EVALUATED at least once. */
+  /**
+   * null until an event OF THIS KIND was evaluated against this subscription.
+   *
+   * NOT "the machinery ran" — see lastScannedAt. Those were one field, and the
+   * collapse is the defect: `evaluate()` only touches subscriptions whose kind
+   * matches the event, so an `item` subscriber sat at `never evaluated` for a
+   * week while `pr` events flowed past it. Its health said the wiring was dead;
+   * the wiring was fine and nothing of its kind had happened.
+   */
   lastEvaluatedAt: number | null;
+  /**
+   * null until a scan RAN with this subscription registered — regardless of
+   * kind. A scan that ran is evidence the wiring works; it says nothing about
+   * whether your kind fired, which is the other field.
+   *
+   * Optional on disk: subscriptions written before this existed have no value,
+   * and absent must read as UNKNOWN rather than as "never scanned". Fabricating
+   * a scan nobody observed is the failure this whole phase is about.
+   */
+  lastScannedAt?: number | null;
   lastEventAt: number | null;
   /** Idempotency keys already delivered, for 6.4. */
   delivered: string[];
@@ -60,17 +78,53 @@ function writeSubs(subs: Subscription[]): void {
  * 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)
+export function subscriptionHealth(s: Subscription): { level: "ok" | "error" | "unknown"; detail: string } {
+  const iso = (n: number) => new Date(n).toISOString();
+
+  // THREE STATES, BECAUSE THERE ARE THREE FACTS. They were two, and the
+  // collapse cost a week: an `item` subscriber read `error — never evaluated`
+  // the whole time, because `evaluate()` only touches subscriptions whose kind
+  // matches the event and no `item` event had fired. The wiring was fine. The
+  // health field said it was dead, and the agent holding it believed the field.
+  //
+  // Same shape as `alive` swallowing `heartbeatFresh`, and as
+  // `stall_clock_status` reporting green while covering nothing: one field
+  // answering two questions always answers the easier one.
+  if (s.lastScannedAt === undefined && s.lastEvaluatedAt === null) {
+    // Written before this field existed AND never evaluated. Absent is UNKNOWN,
+    // never "never scanned" — inventing a scan nobody observed is the failure
+    // this phase is about, and asserting one never happened is the same error
+    // pointed the other way.
+    return {
+      level: "unknown",
+      detail:
+        "predates scan tracking and has never been evaluated — whether the machinery has run for it CANNOT be determined from this record. " +
+        "It will resolve to ok or error on the next scan; until then this is an absence of evidence, not evidence of absence.",
+    };
+  }
+  if (!s.lastScannedAt) {
     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.`,
+      detail:
+        "NEVER SCANNED — no scan has run with this subscription registered, so it has produced no evidence of being wired to anything. " +
+        "This is the state that means broken.",
+    };
+  }
+  if (s.lastEvaluatedAt === null) {
+    // THE STATE THAT USED TO READ AS BROKEN. The machinery ran and nothing of
+    // this kind happened, which is a healthy idle watch.
+    return {
+      level: "ok",
+      detail:
+        `scanned ${iso(s.lastScannedAt)}, never evaluated — the machinery RAN and no '${s.kind}' event has occurred yet. ` +
+        "Scanned-and-quiet is healthy; it is not the same as never run, and those shared a field until now.",
     };
+  }
   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`,
+      ? `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, last event ${iso(s.lastEventAt)}`
+      : `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, no events yet`,
   };
 }
 
@@ -122,12 +176,26 @@ export type Delivery = { subscriptionId: string; agentId: string; key: string; s
  * 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.
  */
+/**
+ * Record that a scan RAN, for every live subscription regardless of kind.
+ *
+ * Called once per scan — including a scan that produced NO events, which is
+ * exactly the case that starved the old field: no events of your kind means
+ * `evaluate` never touches you, and a subscription that is never touched cannot
+ * be told from one that is not wired to anything.
+ */
+export function markScanned(subs: Subscription[], now: number): Subscription[] {
+  return subs.map((s) => ({ ...s, lastScannedAt: now }));
+}
+
 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 };
+    // Every subscription observed this scan, whatever its kind.
+    const scanned = { ...s, lastScannedAt: now };
+    if (s.kind !== ev.kind) return scanned;
+    const evaluated = { ...scanned, 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" });
@@ -157,6 +225,12 @@ export async function subscribeTool(args: { agentId: string; kind: SubKind; targ
     kind: args.kind,
     target: args.target,
     createdAt: Date.now(),
+    // EXPLICIT null, never left absent. `null` means "we know no scan has run
+    // for this"; `undefined` means "this record predates the field and we
+    // cannot say". A subscription created now is the first case, and writing it
+    // explicitly is what keeps a brand-new registration from being reported as
+    // unknowable.
+    lastScannedAt: null,
     lastEvaluatedAt: null,
     lastEventAt: null,
     delivered: [],
@@ -185,6 +259,7 @@ export async function listSubscriptionsTool(args: { agentId?: string }) {
   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");
+  const undetermined = rows.filter((r) => r.health.level === "unknown");
   return {
     ok: neverEvaluated.length === 0,
     // Population beside the verdict, always: "no subscriptions" and "none
@@ -192,7 +267,12 @@ export async function listSubscriptionsTool(args: { agentId?: string }) {
     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.` }
+      ? { error: `${neverEvaluated.length} of ${rows.length} subscription(s) have NEVER BEEN SCANNED — no scan has run with them registered, so they have produced no evidence of being wired to anything.` }
+      : {}),
+    ...(undetermined.length
+      ? {
+          undetermined: `${undetermined.length} of ${rows.length} subscription(s) predate scan tracking and cannot be judged yet — they resolve on the next scan. Reported rather than counted as either healthy or broken.`,
+        }
       : {}),
   };
 }

package/src/tools/record-events.ts

@@ -25,7 +25,7 @@
  * notification for work that then vanishes is worse than a late one.
  */
 import { execFileSync } from "node:child_process";
-import { newlyTickedInDiff, parseWorkDoc, queueItemsOf, doneEntriesOf } from "@davidbalzan/groundwork-seam";
+import { newlyTickedInDiff, parseWorkDoc, queueItemsOf, doneEntriesOf, hasCommitRef } from "@davidbalzan/groundwork-seam";
 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";
@@ -110,8 +110,6 @@ export function prRefsIn(field: string | undefined): string[] {
   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();
 
@@ -167,7 +165,7 @@ export function eventsFromCommittedChange(
   // 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 citedEntries = newEntries.filter((e) => prRefsIn(e.ref).length > 0 || hasCommitRef(e.ref ?? ""));
   const unattributed: string[] = [];
 
   for (const item of removedItems) {
@@ -259,7 +257,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { ROOT } from "../store.js";
-import { readSubs, evaluate, commitEvaluation, eventIsDerived } from "./events.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived, markScanned } from "./events.js";
 
 /**
  * The watermark: the last commit whose record change has been turned into
@@ -351,8 +349,15 @@ export async function scanRecordEventsTool(args: { repo: string; since?: string;
 
   const deliveries: unknown[] = [];
   if (args.write) {
-    let subs = readSubs();
+    // MARK THE SCAN BEFORE THE EVENTS, and unconditionally.
+    //
+    // A scan that produced NO events is exactly the case that starved the old
+    // health field: `evaluate` is per-event, so a quiet scan touched nothing
+    // and every subscription kept reading "never evaluated" — indistinguishable
+    // from unwired. The scan RAN; that is a fact about the machinery and it is
+    // recorded whether or not anything fired.
     const now = Date.now();
+    let subs = markScanned(readSubs(), now);
     for (const ev of emitted) {
       const r = evaluate(subs, ev, now);
       subs = r.subs;

package/src/tools/records.ts

@@ -24,6 +24,7 @@ import {
   type WorkDoc,
   phaseCitationsIn,
   newlyTickedInDiff,
+  sweepTagOf,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
 import { haltState } from "./stall.js";
@@ -151,8 +152,21 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     .sort((a, b) => (PRIORITY_ORDER[a.i.priority ?? "P3"] ?? 3) - (PRIORITY_ORDER[b.i.priority ?? "P3"] ?? 3) || a.idx - b.idx);
 
   const skipped: { item: string; blockedBy: string }[] = [];
+  // NOT WORKER-CLAIMABLE (Task 15.4). Measured: 13-14 of the open queue is
+  // `[SWEEP:canon]`/`[SWEEP:canon.N]` — canon prose the aide and coordinator
+  // author directly into the playbook, never assigned as code work. Handing
+  // one out here is the exact defect: `next_unblocked` offered one outside
+  // the caller's lane while the rest of what remained was this same family.
+  // Skipped VISIBLY, same discipline as a blocked top item — never silently
+  // dropped, so a caller can tell "nothing left for me" from "nothing left".
+  const notClaimable: { item: string; sweepTag: string }[] = [];
   let pick: QueueItem | null = null;
   for (const { i } of ranked) {
+    const tag = sweepTagOf(i);
+    if (tag && /^canon(\.\d+)?$/.test(tag)) {
+      notClaimable.push({ item: keyOf(i), sweepTag: tag });
+      continue;
+    }
     const b = blockedBy(i);
     // NEVER STALL THE LANE waiting on a reorder: a blocked top item is skipped,
     // visibly, and the next unblocked one is taken.
@@ -176,7 +190,15 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
     open: open.length,
     next: pick ? { id: pick.id, priority: pick.priority, text: pick.text } : null,
     skipped,
-    boardHunks: skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
+    // A SEPARATE AXIS from `skipped` (blocked) — this is "not this caller's
+    // to take" rather than "blocked on something else". Collapsing the two
+    // would read a claimability gap as a dependency, which is a different
+    // remedy (route it, don't wait for it).
+    notClaimable,
+    boardHunks: [
+      ...skipped.map((s) => `⏭ skipped — blocked by ${s.blockedBy}`),
+      ...notClaimable.map((s) => `⏭ skipped — not worker-claimable (${s.sweepTag})`),
+    ],
     // A SEPARATE AXIS, deliberately. See noDownstream().
     noDownstream: undiscriminating
       ? {