agent-coord-mcp 0.19.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 };
@@ -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>();

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 } : {}),
     });
   }

package/src/work.ts

@@ -63,6 +63,33 @@ export type BoardRow = {
   raw?: string;
 };
 
+// The one arity BoardRow can hold. boardCells() and the parser's arity guard
+// both reference this constant so the two sides cannot drift; a test pins
+// boardCells().length === BOARD_ARITY.
+export const BOARD_ARITY = 5;
+
+// A table row whose column count does not match BoardRow. It is REFUSED a
+// record (boardRowsOf never returns it) but PRESERVED byte-exactly — the
+// alternative, destructuring whatever arity into a fixed 5-tuple, silently
+// narrowed 6-column rows and widened 4-column ones on export (hit live
+// 2026-07-29: #38's extra `Pane` column was dropped on write-back). Refusing
+// the row rather than throwing keeps one bad row from taking down the whole
+// document's import. The schema decision stays with the board owner: widening
+// BoardRow is a deliberate act (change BOARD_ARITY, boardCells, and this
+// guard together), never something a docs commit does by accident.
+export type MalformedRow = {
+  malformed: true;
+  // Replayed byte-exactly on render — never narrowed, never widened.
+  verbatim: string;
+  // Names the line, quotes the row, states expected/actual — loud enough to
+  // fix from the message alone.
+  issue: string;
+};
+
+export function isMalformedRow(r: BoardRow | MalformedRow): r is MalformedRow {
+  return (r as MalformedRow).malformed === true;
+}
+
 // A parsed document: an ordered block list. `text` blocks are verbatim lines
 // (never interpreted); the others carry records rendered back in place.
 export type Block =
@@ -71,7 +98,7 @@ export type Block =
   | { kind: "done"; entries: DoneEntry[] }
   // `header` and `align` are kept as raw lines for the same reason as
   // BoardRow.raw — the alignment row (`|---|---|`) has no canonical form.
-  | { kind: "board"; header: string; align: string; rows: BoardRow[] };
+  | { kind: "board"; header: string; align: string; rows: (BoardRow | MalformedRow)[] };
 
 export type WorkDoc = {
   // Kept so an export can be written back with the exact byte tail it had.
@@ -182,11 +209,13 @@ function boardCells(r: BoardRow): string[] {
 }
 
 // Replay the original line when the fields still say what it said; re-render
-// once anything actually changed.
-export function renderBoardRow(r: BoardRow): string {
+// once anything actually changed. A malformed row has no fields to have
+// changed — it replays its bytes, always.
+export function renderBoardRow(r: BoardRow | MalformedRow): string {
+  if (isMalformedRow(r)) return r.verbatim;
   if (r.raw !== undefined) {
     const cells = splitRow(r.raw);
-    if (cells.length === 5 && cells.every((c, i) => c === boardCells(r)[i])) return r.raw;
+    if (cells.length === BOARD_ARITY && cells.every((c, i) => c === boardCells(r)[i])) return r.raw;
   }
   return renderRow(boardCells(r));
 }
@@ -280,11 +309,28 @@ export function parseWorkDoc(source: string): WorkDoc {
 
     // Lanes table: a header row followed by an alignment row.
     if (TABLE_ROW.test(line) && TABLE_ALIGN.test(lines[i + 1] ?? "")) {
-      const rows: BoardRow[] = [];
+      const rows: (BoardRow | MalformedRow)[] = [];
       let j = i + 2;
       for (; j < lines.length && TABLE_ROW.test(lines[j] ?? ""); j++) {
         const raw = lines[j] ?? "";
-        const [lane = "", owner = "", state = "", currentSlice = "", nextGo = ""] = splitRow(raw);
+        const cells = splitRow(raw);
+        // Arity guard: a row BoardRow cannot hold is refused a record, kept
+        // verbatim, and named loudly — destructuring it into the 5-tuple is
+        // exactly the silent narrow/widen this exists to prevent. An empty
+        // trailing cell (`| a | b | c | d | |`) is still five columns and
+        // still a legitimate row.
+        if (cells.length !== BOARD_ARITY) {
+          rows.push({
+            malformed: true,
+            verbatim: raw,
+            issue:
+              `board row at line ${j + 1} has ${cells.length} column(s), expected ${BOARD_ARITY} — ` +
+              `refused (kept verbatim, excluded from board records). Fix the row, or widen BoardRow ` +
+              `deliberately (BOARD_ARITY + boardCells + this guard together). Row: ${raw}`,
+          });
+          continue;
+        }
+        const [lane = "", owner = "", state = "", currentSlice = "", nextGo = ""] = cells;
         rows.push({ id: idFor("b", lane), lane, owner, state, currentSlice, nextGo, raw });
       }
       flushText();
@@ -325,5 +371,16 @@ export function doneEntriesOf(doc: WorkDoc): DoneEntry[] {
 }
 
 export function boardRowsOf(doc: WorkDoc): BoardRow[] {
-  return doc.blocks.flatMap((b) => (b.kind === "board" ? b.rows : []));
+  return doc.blocks.flatMap((b) =>
+    b.kind === "board" ? b.rows.filter((r): r is BoardRow => !isMalformedRow(r)) : [],
+  );
+}
+
+// Every refused row's issue, in document order — what makes the parse-time
+// rejection LOUD at the tool layer (import_work/list_work/export_work all
+// surface it) instead of a filtered-out record nobody notices.
+export function workDocIssues(doc: WorkDoc): string[] {
+  return doc.blocks.flatMap((b) =>
+    b.kind === "board" ? b.rows.filter(isMalformedRow).map((r) => r.issue) : [],
+  );
 }