agent-coord-mcp 0.19.0 → 0.23.0

package/src/tools/registry.ts

@@ -46,7 +46,10 @@ import {
   transportFile,
   TRANSPORT_DIR,
   updateJson,
+  listSessionFiles,
+  readJsonStrict,
   type RoomRegistry,
+  type SessionBinding,
 } from "../store.js";
 import { recordAuthorityFor, resolveRole, roleInputSchema, type RoleArg } from "../roles.js";
 import {
@@ -73,6 +76,11 @@ export const registerSchema = {
   agentId: z.string().min(1),
   project: z.string().optional(),
   role: roleInputSchema.optional(),
+  // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
+  // that is LIVE on the bus refuses unless the call presents that agent's
+  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  token: z.string().optional(),
+  force: z.boolean().optional(),
 };
 
 // Work out what `role`/`roleId` should become, or why the update is refused.
@@ -299,6 +307,94 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
+// ---------- first-claim liveness evidence ----------
+// What the TOFU binding guard (server.ts guardFirstClaim) consults before a
+// fresh session may claim an id. Three independent signals say "this id is
+// currently active": a fresh registry heartbeat, a live transport marker, and
+// a live session-binding marker from another pid. The verdict distinguishes
+// VERIFIED ABSENT (state readable, id not live → free to bind; refusing here
+// would break all onboarding) from CANNOT VERIFY (a state file exists but is
+// unreadable → the guard must refuse rather than treat corruption as absence).
+// `samePane`: a live local pusher for the claimed id types into THIS process's
+// own tmux pane — two sessions cannot share a pane, so this is the same seat
+// restarting in place, not a second session claiming a live id.
+
+export type ClaimEvidence = {
+  live: boolean;
+  verifiable: boolean;
+  samePane: boolean;
+  boundElsewhere: number;
+  reasons: string[];
+};
+
+export async function liveClaimEvidence(agentId: string, now: number): Promise<ClaimEvidence> {
+  const reasons: string[] = [];
+  let verifiable = true;
+  let samePane = false;
+  let heartbeatFresh = false;
+  let markerLive = false;
+  let boundElsewhere = 0;
+
+  let reg: AgentRegistry = {};
+  try {
+    reg = await readJsonStrict<AgentRegistry>(AGENTS_FILE, {});
+  } catch {
+    verifiable = false;
+    reasons.push("agents.json exists but cannot be parsed — heartbeat liveness is unverifiable");
+  }
+  const entry = reg[agentId];
+  if (entry && now - entry.lastHeartbeat < STALE_MS) {
+    heartbeatFresh = true;
+    reasons.push(`fresh registry heartbeat ${Math.floor((now - entry.lastHeartbeat) / 1000)}s ago`);
+  }
+
+  let marker: TransportMarker | null = null;
+  try {
+    marker = await readJsonStrict<TransportMarker | null>(transportFile(agentId), null);
+  } catch {
+    verifiable = false;
+    reasons.push("transport marker exists but cannot be parsed — transport liveness is unverifiable");
+  }
+  if (marker && isMarkerLive(marker, reg, now)) {
+    markerLive = true;
+    reasons.push(
+      `live ${marker.transport} transport (pid ${marker.pid}${marker.tmuxTarget ? `, pane ${marker.tmuxTarget}` : ""})`,
+    );
+    if (
+      marker.transport === "tmux-push" &&
+      marker.tmuxTarget &&
+      process.env.TMUX_PANE &&
+      marker.tmuxTarget === process.env.TMUX_PANE
+    ) {
+      samePane = true;
+    }
+  }
+
+  for (const file of await listSessionFiles()) {
+    let s: SessionBinding | null = null;
+    try {
+      s = await readJsonStrict<SessionBinding | null>(file, null);
+    } catch {
+      verifiable = false;
+      reasons.push(`session binding ${path.basename(file)} cannot be parsed — unverifiable (doctor fix cleans it)`);
+      continue;
+    }
+    if (!s || s.agentId !== agentId || s.pid === process.pid) continue;
+    if (isPidAlive(s.pid)) {
+      boundElsewhere++;
+      reasons.push(`another live session (pid ${s.pid}, via ${s.via}) is already bound to this id`);
+    }
+  }
+
+  return {
+    live: heartbeatFresh || markerLive || boundElsewhere > 0,
+    verifiable,
+    samePane,
+    boundElsewhere,
+    reasons,
+  };
+}
+
 // ---------- rename_agent (NICK) ----------
 
 export const renameAgentSchema = {

package/src/tools/render.ts

@@ -1,80 +1 @@
-// Typed record → the text layout the fleet already reads (Phase 8 Task 3.3).
-//
-// Every consumer downstream of a message — hooks/tier.mjs's prefix table, the
-// UI's alert parser, a human reading a tmux pane — reads `text`. Phase 8 adds
-// `record` alongside it, so the rendering must reproduce the byte layout those
-// consumers already expect. Nothing downstream changes while agents migrate.
-//
-// This is a pure function of the record: no clock, no I/O, no registry. It
-// never sees `from`, `to`, or anything the sender could use it to forge.
-
-import type { DecisionPayload, MessageRecord, SummaryPayload, VerdictPayload } from "./shared.js";
-
-// The case-sensitive prefixes at byte 0 of `text`, exactly as classifyTier
-// matches them. `decision` is absent because it renders as a multi-line block,
-// not a one-liner.
-const PREFIX: Record<string, string> = {
-  blocker: "BLOCKER",
-  risk: "RISK",
-  done: "DONE",
-  fyi: "FYI",
-  action: "AGENT_ACTION",
-  go: "GO",
-  scope: "SCOPE CHANGE",
-  // `verdict` has no prefix in the v1 vocabulary — it is new in Phase 8. A gate
-  // PASS/FAIL was previously posted as prose, which is why verdicts could not
-  // be routed. Rendering it under its own prefix gives it one.
-  verdict: "VERDICT",
-};
-
-function isNonEmpty(v: unknown): v is string {
-  return typeof v === "string" && v.trim().length > 0;
-}
-
-// The playbook's decision packet (§Decision Packet Format), byte-for-byte —
-// the UI parses this into a clickable decision card, and a layout that drifts
-// still alerts loudly but loses the card. Returns null when any of the five
-// fields is missing, so the caller can reject rather than emit a half packet.
-function renderDecision(p: DecisionPayload): string | null {
-  if (!isNonEmpty(p.title) || !isNonEmpty(p.context)) return null;
-  if (!isNonEmpty(p.recommendation) || !isNonEmpty(p.ifNoAction)) return null;
-  if (!Array.isArray(p.options) || p.options.length === 0) return null;
-  if (!p.options.every(isNonEmpty)) return null;
-  return [
-    `DAVID_DECISION: ${p.title}`,
-    `Context: ${p.context}`,
-    "Options:",
-    ...p.options.map((o, i) => `${i + 1}. ${o}`),
-    `Recommendation: ${p.recommendation}`,
-    `If no action: ${p.ifNoAction}`,
-  ].join("\n");
-}
-
-// `VERDICT: PASS <sha> — <notes>`. The sha is not optional in the rendering:
-// a verdict that doesn't name the commit it was issued against is
-// unfalsifiable the moment the branch moves.
-function renderVerdict(p: VerdictPayload): string | null {
-  if (p.result !== "pass" && p.result !== "fail") return null;
-  if (!isNonEmpty(p.headRefOid)) return null;
-  const head = `${PREFIX.verdict}: ${p.result.toUpperCase()} ${p.headRefOid}`;
-  return isNonEmpty(p.notes) ? `${head} — ${p.notes}` : head;
-}
-
-// Render a record to its text form, or null when the payload can't support one
-// (absent, or missing a field the layout needs). Null is not an error here —
-// the caller decides whether a record without a rendering is fatal, and it only
-// is when there's no author-supplied `text` to fall back on.
-export function renderRecord(record: MessageRecord): string | null {
-  if (!record || typeof record.type !== "string") return null;
-  const payload = record.payload as unknown;
-  if (payload === undefined || payload === null) return null;
-  if (typeof payload !== "object" || Array.isArray(payload)) return null;
-
-  if (record.type === "decision") return renderDecision(payload as DecisionPayload);
-  if (record.type === "verdict") return renderVerdict(payload as VerdictPayload);
-
-  const prefix = PREFIX[record.type];
-  if (!prefix) return null;
-  const { summary } = payload as SummaryPayload;
-  return isNonEmpty(summary) ? `${prefix}: ${summary}` : null;
-}
+export { renderRecord, PREFIX } from "@davidbalzan/groundwork-seam/protocol";

package/src/tools/shared.ts

@@ -1,3 +1,12 @@
+import type {
+  Citation,
+  DecisionPayload,
+  MessageRecord,
+  MessageRecordType,
+  SummaryPayload,
+  SummaryRecordType,
+  VerdictPayload,
+} from "@davidbalzan/groundwork-seam/protocol";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -92,82 +101,16 @@ export type TransportMarker = {
 
 export type AgentRegistry = Record<string, AgentEntry>;
 
-// Where a claim can be independently verified. The point is that a consumer
-// resolves the ref (gh, git, fs) instead of trusting the message body — a
-// `done` record whose PR ref doesn't exist is a false claim, not a typo.
-export type Citation = {
-  kind: "pr" | "file" | "commit" | "url";
-  ref: string;
+export type {
+  Citation,
+  MessageRecordType,
+  DecisionPayload,
+  VerdictPayload,
+  SummaryPayload,
+  SummaryRecordType,
+  MessageRecord,
 };
 
-// The protocol vocabulary the fleet already speaks. Today these live as
-// case-sensitive prefixes at byte 0 of `text` (hooks/tier.mjs), parsed a
-// second time by the UI for alert priority — so a greeting before the prefix
-// silently downgrades a production blocker, and the two parsers can disagree
-// about the same message. As a field there is nothing to mis-parse.
-export type MessageRecordType =
-  | "blocker"   // BLOCKER:        work cannot continue
-  | "decision"  // DAVID_DECISION: the human must decide
-  | "risk"      // RISK:           quality/security/cost/product risk
-  | "done"      // DONE:           completed work, must cite
-  | "fyi"       // FYI:            no action needed
-  | "action"    // AGENT_ACTION:   another agent can handle it
-  | "go"        // GO:             a work order
-  | "scope"     // SCOPE CHANGE:   amends a contract in flight
-  | "verdict";  // (new) a gate PASS/FAIL — has no prefix today
-
-// The five fields of the playbook's decision packet (§Decision Packet Format).
-// Named to match that layout because `renderRecord` reproduces it byte-for-byte
-// — the UI parses the rendering into a clickable decision card.
-export type DecisionPayload = {
-  title: string;
-  context: string;
-  options: string[];
-  recommendation: string;
-  ifNoAction: string;
-};
-
-// A gate verdict. `headRefOid` pins WHICH commit was gated: a PASS that doesn't
-// name the sha it was issued against is unfalsifiable once the branch moves.
-export type VerdictPayload = {
-  result: "pass" | "fail";
-  headRefOid: string;
-  notes?: string;
-};
-
-// Everything else carries prose. One line, because these render as
-// `<PREFIX>: <summary>` and a paragraph in a tmux pane is a wall, not a status.
-export type SummaryPayload = { summary: string };
-
-// Message types whose payload is just a summary.
-export type SummaryRecordType = "blocker" | "risk" | "fyi" | "action" | "go" | "scope";
-
-// Structured counterpart to `text`, NOT a replacement: `text` is the rendering,
-// and a tmux pane can only receive text. A v1 agent that has never heard of
-// `record` omits it entirely and behaves byte-identically.
-//
-// `payload` stays OPTIONAL on every arm — Phase 8 is additive, so no new
-// required field may appear on the wire. What is pinned is the shape *if* a
-// payload is supplied: a `decision` carrying three of its five fields is
-// structurally wrong for the type it claims and is rejected, while a payload
-// with extra unknown keys passes through untouched (a v3 sender must not be
-// broken by a v2 server, and stripping would silently drop data on the way to
-// disk).
-//
-// `cites` is likewise optional here. `done` requires a PR citation, but that is
-// enforced in sendMessageTool as a plain {ok:false,error} rather than a schema
-// rejection — see the identity-binding precedent in src/server.ts.
-//
-// UNTRUSTED, exactly like `from`. A peer can claim any type here, so trust
-// decisions (the SCOPE countersignature, gate-runner routing) must still
-// resolve the sender against the registry — typed is not the same as
-// authenticated, and `record` must never become a path to setting `urgent`.
-export type MessageRecord =
-  | { type: "decision"; payload?: DecisionPayload; cites?: Citation[] }
-  | { type: "verdict"; payload?: VerdictPayload; cites?: Citation[] }
-  | { type: "done"; payload?: SummaryPayload; cites?: Citation[] }
-  | { type: SummaryRecordType; payload?: SummaryPayload; cites?: Citation[] };
-
 export type Message = {
   id: string;
   ts: number;
@@ -215,9 +158,7 @@ export type Message = {
 //
 // Deliberately structural about `record`: it takes anything with the two
 // fields, so status entries and archive rows can be passed without a cast.
-export function isDecision(e: { kind?: string; record?: { type?: string } } | null | undefined): boolean {
-  return e?.kind === "decision" || e?.record?.type === "decision";
-}
+export { isDecision } from "@davidbalzan/groundwork-seam/protocol";
 
 export type StatusEntry = {
   id: string;

package/src/tools/transport.ts

@@ -31,7 +31,9 @@ import {
   inboxFile,
   listCursorFiles,
   listInboxFiles,
+  listSessionFiles,
   listTransportFiles,
+  type SessionBinding,
   logFile,
   memberRooms,
   normalizeRoom,
@@ -192,7 +194,21 @@ export const sendCommandSchema = {
 
 // A receipt as the pusher writes it. `submitted` is present only on control
 // receipts from a pusher new enough to VERIFY submission (v0.19.0+).
-type Receipt = { id: string; ts: number; control?: boolean; submitted?: boolean; verified?: boolean; reason?: string };
+// `scriptMtime` is the reporting pusher's build identity — the same
+// module-graph stamp the transport marker carries (newest mtime across the
+// pusher's entry file AND its hooks/ imports, per #28: the stale part is as
+// likely submit.mjs as the entrypoint). It is honesty, not security: a lying
+// pusher defeats it, exactly like report_transport. The value is that a
+// "confirmed" can be tied to the code that did the confirming.
+type Receipt = {
+  id: string;
+  ts: number;
+  control?: boolean;
+  submitted?: boolean;
+  verified?: boolean;
+  reason?: string;
+  scriptMtime?: number;
+};
 
 // Poll an agent's receipt log until a receipt for `msgId` appears or the
 // deadline passes. Returns the receipt, or null on timeout. File-only — no
@@ -221,18 +237,38 @@ async function waitForReceipt(agentId: string, msgId: string, timeoutMs: number)
 // pending with a reason the caller can act on. Reporting an unverified
 // submission as confirmed is the defect this exists to remove: a check that
 // cannot fail loudly is worse than no check.
+//
+// `pusherSourceMtime` (the caller passes newestPusherSourceMtime()) lets a
+// CONFIRMED verdict carry a note when the reporting pusher's build identity
+// is behind the on-disk pusher source, or absent entirely. The note never
+// downgrades the verdict — the command demonstrably ran — it says whose
+// verification logic said so. Absence of the stamp reads as UNKNOWN, never
+// as fresh (same ruling as doctor's stale-pusher-script / provenance
+// checks: absence is not exemption), and the absence note is issued before
+// the on-disk comparison so an unstattable hooks dir cannot silence it.
 export function deliveryOutcome(
   agentId: string,
   receipt: Receipt | null,
   timeoutMs: number,
-): { delivery: "confirmed" | "pending"; at?: number; reason?: string } {
+  pusherSourceMtime?: number,
+): { delivery: "confirmed" | "pending"; at?: number; reason?: string; note?: string } {
   if (!receipt) {
     return {
       delivery: "pending",
       reason: `no delivery receipt from '${agentId}' within ${timeoutMs}ms — the command was written but may not have reached the pane (stale/wedged pusher). Run doctor or re-attach the agent.`,
     };
   }
-  if (receipt.submitted === true) return { delivery: "confirmed", at: receipt.ts };
+  if (receipt.submitted === true) {
+    let note: string | undefined;
+    if (receipt.scriptMtime === undefined) {
+      note = `'${agentId}' confirmed the submission, but its pusher carries no build-identity stamp — the pusher predates receipt provenance and this confirmation cannot be tied to any known code; re-attach the agent (detach_agent + attach_agent) to upgrade it.`;
+    } else if (pusherSourceMtime !== undefined && receipt.scriptMtime < pusherSourceMtime - 1) {
+      const loaded = new Date(receipt.scriptMtime).toISOString();
+      const ondisk = new Date(pusherSourceMtime).toISOString();
+      note = `'${agentId}' confirmed the submission, but its pusher loaded its code at ${loaded} and the on-disk pusher source is newer (${ondisk}) — the verification logic behind this confirmation predates the current code; re-attach the agent (detach_agent + attach_agent) to upgrade it.`;
+    }
+    return { delivery: "confirmed", at: receipt.ts, ...(note ? { note } : {}) };
+  }
   if (receipt.submitted === false) {
     return {
       delivery: "pending",
@@ -351,7 +387,7 @@ export async function sendCommandTool(args: {
     const wait = args.waitForDelivery ?? true;
     const deliveryTimeoutMs = args.deliveryTimeoutMs ?? 8000;
     const receipt = wait ? await waitForReceipt(args.to, msg.id, deliveryTimeoutMs) : null;
-    const outcome = wait ? deliveryOutcome(args.to, receipt, deliveryTimeoutMs) : null;
+    const outcome = wait ? deliveryOutcome(args.to, receipt, deliveryTimeoutMs, newestPusherSourceMtime()) : null;
     const confirmed = outcome?.delivery === "confirmed";
     // After /clear the receiver forgets its identity and that it's bus-attached
     // (the system prompt isn't re-applied because /clear isn't a session
@@ -373,7 +409,10 @@ export async function sendCommandTool(args: {
             delivery: outcome.delivery,
             confirmed,
             ...(outcome.at !== undefined ? { deliveredAt: outcome.at } : {}),
-            ...(confirmed ? {} : { warning: outcome.reason }),
+            // A confirmed delivery can still warn: the note names a reporting
+            // pusher whose build identity is stale or absent. `confirmed`
+            // stays true — the command ran; the warning is about who said so.
+            ...(confirmed ? (outcome.note ? { warning: outcome.note } : {}) : { warning: outcome.reason }),
           }
         : {}),
       ...(reminderMs > 0 ? { reminderScheduled: { delayMs: reminderMs, recipients: [args.to] } } : {}),
@@ -409,11 +448,13 @@ export async function sendCommandTool(args: {
   let confirmed: string[] = [];
   let pending: string[] = [];
   let pendingReasons: string[] = [];
+  let confirmNotes: string[] = [];
   if (wait) {
+    const sourceMtime = newestPusherSourceMtime();
     const results = await Promise.all(
       delivered.map(async (m) => ({
         m,
-        outcome: deliveryOutcome(m, await waitForReceipt(m, msg.id, deliveryTimeoutMs), deliveryTimeoutMs),
+        outcome: deliveryOutcome(m, await waitForReceipt(m, msg.id, deliveryTimeoutMs), deliveryTimeoutMs, sourceMtime),
       })),
     );
     confirmed = results.filter((r) => r.outcome.delivery === "confirmed").map((r) => r.m);
@@ -421,6 +462,9 @@ export async function sendCommandTool(args: {
     pendingReasons = results
       .filter((r) => r.outcome.delivery !== "confirmed")
       .map((r) => `${r.m}: ${r.outcome.reason}`);
+    confirmNotes = results
+      .filter((r) => r.outcome.delivery === "confirmed" && r.outcome.note)
+      .map((r) => r.outcome.note!);
   }
   // Same post-/clear re-anchor as the DM path — one reminder per delivered
   // member, in their own inbox, with their own agentId in the body.
@@ -444,6 +488,9 @@ export async function sendCommandTool(args: {
                 warning: `not confirmed as submitted within ${deliveryTimeoutMs}ms — ${pendingReasons.join(" | ")}`,
               }
             : {}),
+          // Confirmed members whose reporting pusher is stale or unstamped —
+          // the confirmations stand, the notes say whose code issued them.
+          ...(confirmNotes.length ? { notes: confirmNotes } : {}),
         }
       : {}),
     ...(reminderMs > 0 ? { reminderScheduled: { delayMs: reminderMs, recipients: delivered } } : {}),
@@ -712,6 +759,11 @@ export const joinSchema = {
   // false → never; object → attach with overrides.
   attach: z.union([z.boolean(), joinAttachOptionsSchema]).optional(),
   readInbox: z.boolean().optional(),
+  // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
+  // that is LIVE on the bus refuses unless the call presents that agent's
+  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  token: z.string().optional(),
+  force: z.boolean().optional(),
 };
 
 export async function joinTool(args: {
@@ -827,6 +879,13 @@ export const reportReceiptSchema = {
   submitted: z.boolean().optional(),
   verified: z.boolean().optional(),
   reason: z.string().optional(),
+  // Build identity of the reporting pusher: newest mtime across its loaded
+  // module graph (entry file + hooks/ imports), sampled once at its startup —
+  // the same basis report_transport's scriptMtime uses. Absent → the receipt's
+  // provenance is UNKNOWN and deliveryOutcome says so; the server never
+  // defaults it (a default here would be assume-fresh, the twin of the
+  // assume-success `submitted` refuses to invent).
+  scriptMtime: z.number().optional(),
 };
 
 // Wire-callable counterpart to the local pusher's receipt stamp (writeReceipts
@@ -852,6 +911,7 @@ export async function reportReceiptTool(args: {
   submitted?: boolean;
   verified?: boolean;
   reason?: string;
+  scriptMtime?: number;
 }) {
   const receipt: Receipt & { agentId: string; from?: string } = {
     id: args.id,
@@ -862,6 +922,7 @@ export async function reportReceiptTool(args: {
     ...(args.submitted !== undefined ? { submitted: args.submitted } : {}),
     ...(args.verified !== undefined ? { verified: args.verified } : {}),
     ...(args.reason !== undefined ? { reason: args.reason } : {}),
+    ...(args.scriptMtime !== undefined ? { scriptMtime: args.scriptMtime } : {}),
   };
   await appendJsonl(receiptFile(args.agentId), receipt);
   return { ok: true, receipt };
@@ -1184,6 +1245,55 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     });
   }
 
+  // 1d. Duplicate session bindings — two live MCP sessions bound to one agent
+  //     id means two processes are ACTING as the same agent (the
+  //     disavow-liaison shape: a dev session bound onto a live worker's id;
+  //     force/token make that possible on purpose, this makes it visible).
+  //     Bindings are per-process closure state, so this reads the on-disk
+  //     session markers stdio servers write at bind time. A marker whose pid
+  //     is dead is litter from a killed session (default signal death skips
+  //     exit handlers) — cleaned under fix. Live duplicates are NOT auto-
+  //     fixable: doctor cannot know which of two running sessions is the
+  //     impostor; the wrong session should `quit` (its marker clears on exit).
+  {
+    const byAgent = new Map<string, { pid: number; via: string; boundAt: number }[]>();
+    const stale: string[] = [];
+    for (const file of await listSessionFiles()) {
+      const s = await readJson<SessionBinding | null>(file, null);
+      if (!s || typeof s.pid !== "number" || !s.agentId || !isPidAlive(s.pid)) {
+        stale.push(path.basename(file));
+        if (fix) {
+          await deleteFile(file);
+          fixed.push(`deleted stale session binding ${path.basename(file)}`);
+        }
+        continue;
+      }
+      const list = byAgent.get(s.agentId) ?? [];
+      list.push({ pid: s.pid, via: s.via ?? "unknown", boundAt: s.boundAt ?? 0 });
+      byAgent.set(s.agentId, list);
+    }
+    const dupes: string[] = [];
+    for (const [id, list] of byAgent) {
+      if (list.length < 2) continue;
+      dupes.push(
+        `${id} — ${list
+          .map((b) => `pid ${b.pid} (via ${b.via}, bound ${b.boundAt ? new Date(b.boundAt).toISOString() : "unknown"})`)
+          .join(" AND ")}`,
+      );
+    }
+    findings.push({
+      check: "duplicate-session-binding",
+      level: dupes.length ? "warn" : "ok",
+      detail: dupes.length
+        ? `${dupes.length} agent id(s) bound by more than one live session — two processes are acting as the same agent. Decide which is legitimate; the other should quit (its binding clears on exit).`
+        : stale.length
+          ? `no duplicate session bindings (${stale.length} stale binding file(s) from dead sessions${fix ? " — cleaned" : "; run doctor with fix:true to clean"})`
+          : "no duplicate session bindings",
+      fixable: true,
+      items: dupes.length ? dupes : undefined,
+    });
+  }
+
   // 2. Orphan room memberships (member not in the registry).
   {
     const orphans = new Set<string>();