agent-coord-mcp 0.18.0 → 0.19.1

package/src/tools/admin.ts

@@ -118,11 +118,22 @@ export async function pruneTool(args: {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   const decisionCutoff = Date.now() - decisionDays * 24 * 60 * 60 * 1000;
   const dryRun = args.dryRun ?? false;
-  // room-scoped prune touches only that channel's messages; targets narrows
-  // the sweep otherwise. Default remains "everything".
+  // `room` scopes every sweep to that channel; `targets` narrows which sweeps
+  // run. They compose: `room` only changes the DEFAULT target set, so an
+  // explicit `targets` always wins.
+  //
+  // WHY (regression): this previously read `scopedRoom ? ["rooms"] : args.targets`,
+  // which silently DISCARDED an explicit `targets` whenever `room` was passed.
+  // `prune {room, targets:["members"], dryRun:true}` therefore reported
+  // `orphanMembers: []` because the member sweep never ran — a caller asking
+  // "which members are phantoms in this room" got a clean bill of health that
+  // had not been computed, while `roomMessages` (the one target the override
+  // left enabled) reported real messages a live run would have archived. Field
+  // report: two members that `ping` called `unregistered` were invisible here.
+  // A sweep must never answer a question it did not evaluate.
   const scopedRoom = args.room ? normalizeRoom(args.room) : undefined;
   const targets = new Set<PruneTarget>(
-    scopedRoom ? ["rooms"] : args.targets ?? [...PRUNE_TARGETS]
+    args.targets ?? (scopedRoom ? ["rooms"] : [...PRUNE_TARGETS])
   );
   const keep = (e: { ts: number; kind?: string }) => keepEntry(e, cutoff, decisionCutoff);
 
@@ -133,6 +144,10 @@ export async function pruneTool(args: {
   const staleAgent = (m: string) => !knownAgents.has(m) || (reg[m]?.lastHeartbeat ?? 0) <= cutoff;
 
   const channels = scopedRoom ? [scopedRoom] : Object.keys(await getRooms());
+  // The membership sweeps walk the room registry rather than `channels`, so they
+  // need the scope predicate explicitly — without it, `room` scoped the message
+  // sweep while membership silently swept EVERY room.
+  const inScope = (chan: string) => !scopedRoom || chan === scopedRoom;
 
   if (dryRun) {
     let roomMessages = 0;
@@ -159,6 +174,7 @@ export async function pruneTool(args: {
     if (targets.has("members")) {
       const rooms = await getRooms();
       for (const [chan, e] of Object.entries(rooms)) {
+        if (!inScope(chan)) continue;
         const remaining: string[] = [];
         for (const m of e.members ?? []) {
           if (!knownAgents.has(m)) orphanMembers.add(m);
@@ -264,7 +280,8 @@ export async function pruneTool(args: {
   const archivedRooms: string[] = [];
   if (targets.has("members")) {
     await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-      for (const e of Object.values(current)) {
+      for (const [chan, e] of Object.entries(current)) {
+        if (!inScope(chan)) continue;
         if ((e.members?.length ?? 0) === 0) continue;
         e.members = (e.members ?? []).filter((m) => {
           if (!knownAgents.has(m)) {
@@ -284,7 +301,7 @@ export async function pruneTool(args: {
     if (args.archiveEmptyRooms ?? true) {
       const rooms = await getRooms();
       for (const [chan, e] of Object.entries(rooms)) {
-        if (chan === DEFAULT_ROOM || (e.members?.length ?? 0) > 0) continue;
+        if (chan === DEFAULT_ROOM || !inScope(chan) || (e.members?.length ?? 0) > 0) continue;
         const file = roomFile(chan);
         const msgs = await readJsonl<Message>(file);
         const lastTs = msgs[msgs.length - 1]?.ts ?? 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/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 };
@@ -983,12 +1044,22 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   {
     const localPusherMtime = newestPusherSourceMtime();
     const stale: string[] = [];
+    const unverifiable: string[] = [];
     for (const fname of await listTransportFiles()) {
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify
-      if (marker.scriptMtime === undefined) continue; // pre-v0.8.2 marker, no info
+      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (marker.scriptMtime === undefined) {
+        // ABSENCE IS NOT EXEMPTION. The field's own writer once dropped it,
+        // and the silent skip here meant the check was disabled by the very
+        // thing it monitors — a live pusher we cannot verify is a warn, not
+        // an ok (credit agent-coordination-david-dev). Same flip, same
+        // commit, as serverBuildMtime below: the two checks must never
+        // disagree about what absence means.
+        unverifiable.push(`${marker.agentId} (pid ${marker.pid}, no scriptMtime stamp — cannot verify; detach_agent + attach_agent to re-stamp)`);
+        continue;
+      }
       if (localPusherMtime === undefined) continue;
       if (marker.scriptMtime < localPusherMtime - 1) { // -1ms slack for fs mtime rounding
         const loaded = new Date(marker.scriptMtime).toISOString();
@@ -996,14 +1067,15 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
         stale.push(`${marker.agentId} (pid ${marker.pid}, loaded ${loaded}, on-disk now ${ondisk})`);
       }
     }
+    const bad = [...stale, ...unverifiable];
     findings.push({
       check: "stale-pusher-script",
-      level: stale.length ? "warn" : "ok",
-      detail: stale.length
-        ? `${stale.length} attached pusher(s) running pre-upgrade code — control commands (/clear, /compact) may be silently dropped. Run detach_agent + attach_agent for each, or have the agent relaunch.`
+      level: bad.length ? "warn" : "ok",
+      detail: bad.length
+        ? `${stale.length} attached pusher(s) running pre-upgrade code and ${unverifiable.length} whose freshness cannot be verified (no stamp) — control commands (/clear, /compact) may be silently dropped. Run detach_agent + attach_agent for each, or have the agent relaunch.`
         : "all attached pushers are running the current on-disk script",
       fixable: false,
-      items: stale.length ? stale : undefined,
+      items: bad.length ? bad : undefined,
     });
   }
 
@@ -1062,17 +1134,26 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   {
     const onDisk = onDiskBuildMtime();
     const outdated: string[] = [];
+    const unverifiable: string[] = [];
     for (const fname of await listTransportFiles()) {
       const file = path.join(TRANSPORT_DIR, fname);
       const marker = await readJson<TransportMarker | null>(file, null);
       if (!marker || !isMarkerLive(marker, reg, now)) continue;
-      if (marker.transport !== "tmux-push") continue; // remote = can't verify
-      // Absent field = pre-upgrade marker: SKIP, deliberately mirroring the
-      // scriptMtime semantics in 1b. Two checks holding different opinions
-      // about the same absence would be harder to see than either behaviour
-      // alone — the queued P2 ("missing scriptMtime is a skip, not a warn")
-      // flips BOTH together. Do not "fix" one half here.
-      if (marker.serverBuildMtime === undefined) continue;
+      if (marker.transport !== "tmux-push") continue; // remote = can't verify (documented limit: can't stat another host)
+      if (marker.serverBuildMtime === undefined) {
+        // ABSENCE IS NOT EXEMPTION — flipped in the same commit as the
+        // scriptMtime absence above, so the two checks can never disagree
+        // about what a missing stamp means. An unstamped marker was written
+        // by a pre-provenance server (or by hand): precisely the population
+        // this check exists to police, and the one it must not exempt.
+        // Transition is deliberately correct-and-loud: after the upgrade,
+        // every pre-existing marker warns at once, each cleared by a session
+        // restart + re-attach — the burst is also the only external view of
+        // which sessions still run pre-provenance servers, since a stale
+        // server cannot self-report (see 1b²).
+        unverifiable.push(`${marker.agentId} (no serverBuildMtime stamp — stamped by a pre-provenance server; restart that session, then detach_agent + attach_agent)`);
+        continue;
+      }
       if (onDisk === undefined) continue;
       if (marker.serverBuildMtime < onDisk - 1) {
         const stamped = new Date(marker.serverBuildMtime).toISOString();
@@ -1080,14 +1161,15 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
         outdated.push(`${marker.agentId} (stamped by server build ${stamped}, on-disk build ${current})`);
       }
     }
+    const bad = [...outdated, ...unverifiable];
     findings.push({
       check: "marker-server-provenance",
-      level: outdated.length ? "warn" : "ok",
-      detail: outdated.length
-        ? `${outdated.length} transport marker(s) stamped by a server build older than dist/ — the stamping/spawn logic (freshness basis, pusher argv) predates the current code. Restart that agent's session, then detach_agent + attach_agent.`
+      level: bad.length ? "warn" : "ok",
+      detail: bad.length
+        ? `${outdated.length} transport marker(s) stamped by a server build older than dist/ and ${unverifiable.length} with no provenance stamp at all — the stamping/spawn logic (freshness basis, pusher argv) predates or cannot be tied to the current code. Restart that agent's session, then detach_agent + attach_agent.`
         : "all local transport markers were stamped by the current server build",
       fixable: false,
-      items: outdated.length ? outdated : undefined,
+      items: bad.length ? bad : undefined,
     });
   }
 
@@ -1163,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>();

package/src/tools/work.ts

@@ -13,6 +13,7 @@ import {
   parseWorkDoc,
   queueItemsOf,
   renderWorkDoc,
+  workDocIssues,
 } from "../work.js";
 import { loadScopes, ownsDocument } from "./scopes.js";
 import { AGENTS_FILE } from "../store.js";
@@ -110,18 +111,28 @@ export async function importWorkTool(args: { project: string; repo?: string }) {
   const state: WorkState = { project: args.project, repo, importedAt: Date.now(), docs };
   await saveState(state);
 
+  const allIssues = docs.flatMap((d) => workDocIssues(d.doc).map((issue) => `${d.path}: ${issue}`));
   return {
     ok: true as const,
     project: args.project,
     repo,
     file: workFile(args.project),
-    imported: docs.map((d) => ({
-      path: d.path,
-      kind: d.kind,
-      queue: queueItemsOf(d.doc).length,
-      done: doneEntriesOf(d.doc).length,
-      board: boardRowsOf(d.doc).length,
-    })),
+    imported: docs.map((d) => {
+      const issues = workDocIssues(d.doc);
+      return {
+        path: d.path,
+        kind: d.kind,
+        queue: queueItemsOf(d.doc).length,
+        done: doneEntriesOf(d.doc).length,
+        board: boardRowsOf(d.doc).length,
+        ...(issues.length ? { issues } : {}),
+      };
+    }),
+    ...(allIssues.length
+      ? {
+          warning: `${allIssues.length} table row(s) were refused a record (wrong column count) and kept verbatim — the documents round-trip unchanged, but these rows are invisible to board consumers until fixed. See imported[].issues.`,
+        }
+      : {}),
     note: "the markdown remains authoritative — this store is a derived index",
   };
 }
@@ -161,10 +172,12 @@ export async function listWorkTool(args: {
   const queue: QueueItem[] = [];
   const done: DoneEntry[] = [];
   const board: BoardRow[] = [];
+  const issues: string[] = [];
   for (const d of state.docs) {
     queue.push(...queueItemsOf(d.doc));
     done.push(...doneEntriesOf(d.doc));
     board.push(...boardRowsOf(d.doc));
+    issues.push(...workDocIssues(d.doc).map((issue) => `${d.path}: ${issue}`));
   }
 
   const openQueue = args.includeDone ? queue : queue.filter((q) => !q.done);
@@ -178,6 +191,9 @@ export async function listWorkTool(args: {
     ...(args.kind === "queue" || args.kind === undefined ? { queue: filtered } : {}),
     ...(args.kind === "done" || args.kind === undefined ? { done } : {}),
     ...(args.kind === "board" || args.kind === undefined ? { board } : {}),
+    // A row refused for wrong arity is absent from `board` — say so rather
+    // than let the absence read as "that lane doesn't exist".
+    ...(issues.length ? { issues } : {}),
   };
 }
 
@@ -245,11 +261,16 @@ export async function exportWorkTool(args: {
       : undefined;
 
     if (write && rendered !== current) await fsp.writeFile(target, rendered, "utf8");
+    const issues = workDocIssues(d.doc);
     files.push({
       path: d.path,
       bytes: Buffer.byteLength(rendered, "utf8"),
       identical: rendered === current,
       written: write && rendered !== current,
+      // Refused rows replay verbatim — the write is byte-faithful — but a
+      // caller rewriting a document should hear that some rows carry no
+      // record, rather than infer health from `identical:true`.
+      ...(issues.length ? { issues } : {}),
       ...(scope ? { scope } : {}),
     });
   }