@eamonpluto/agentboard 2.3.0 → 2.4.1

package/bin/agentboard.js

@@ -26,6 +26,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
 
 const MAX_BODY_CHARS = 8000;
 const BOARD_VERSION = 2;
@@ -82,13 +83,27 @@ function refuseDriveRootBoard(root, args) {
   } catch {}
   if (exists) return;
   if (path.dirname(root) === path.parse(root).root) {
+    const cwd = process.cwd();
     fail(
-      `refusing to create a board at drive root ${root} — no project board found above cwd. ` +
-        `Run from your project, pass --board <path>, or set AGENTBOARD_DIR.`
+      `refusing to create a board at drive root ${root} — no project board found above cwd "${cwd}". ` +
+        `Run from your project (the dir containing .agentboard/), pass --board <absolute path to .agentboard>, or set AGENTBOARD_DIR. ` +
+        `Every send echoes [board <path>] — if two agents see different boards, point them at the same one.`
     );
   }
 }
 
+// Best-effort git revision for the project containing the board, so recipients
+// can tell whether cited file:line numbers are stale. Never throws.
+function gitRevForBoard(root) {
+  try {
+    const cwd = path.dirname(root);
+    const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"], timeout: 3000 });
+    return String(out).trim().slice(0, 40) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function dirs(root) {
   return {
     root,
@@ -102,7 +117,8 @@ function ensureBoard(root) {
   const d = dirs(root);
   for (const p of [d.root, d.agents, d.dm, d.delivered]) {
     fs.mkdirSync(p, { recursive: true });
-  }  const metaPath = path.join(d.root, "board.json");
+  }
+  const metaPath = path.join(d.root, "board.json");
   if (!fs.existsSync(metaPath)) {
     fs.writeFileSync(
       metaPath,
@@ -117,9 +133,22 @@ function readJson(p) {
 }
 
 function writeJson(p, obj) {
-  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  const tmp = p + "." + process.pid + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
-  fs.renameSync(tmp, p);
+  // tmp+rename keeps each write atomic under parallel sends; Windows AV
+  // scanners can briefly hold the tmp file, so retry once before giving up.
+  try {
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    const start = Date.now();
+    while (Date.now() - start < 50) { /* brief spin */ }
+    try {
+      fs.renameSync(tmp, p);
+    } catch (e2) {
+      try { fs.rmSync(tmp, { force: true }); } catch {}
+      throw e2;
+    }
+  }
 }
 
 /** Atomic fire-once claim: create file only if it does not exist. */
@@ -144,7 +173,9 @@ function newId(prefix) {
     String(t.getUTCHours()).padStart(2, "0") +
     String(t.getUTCMinutes()).padStart(2, "0") +
     String(t.getUTCSeconds()).padStart(2, "0");
-  return `${prefix}-${stamp}-${crypto.randomBytes(3).toString("hex")}`;
+  // 4 random bytes (8 hex) + pid fragment: parallel sends in the same second
+  // from different processes still get unique ids.
+  return `${prefix}-${stamp}-${crypto.randomBytes(4).toString("hex")}`;
 }
 
 function sanitizeName(name, what) {
@@ -161,7 +192,36 @@ function getFlag(args, flag) {
 
 // Positional args with flag values removed (so `send --from alice --to bob`
 // with no body doesn't mistake "alice bob" for a message).
-const VALUE_FLAGS = new Set(["--from", "--to", "--body", "--session", "--board", "--limit", "--after", "--timeout"]);
+const VALUE_FLAGS = new Set(["--from", "--to", "--body", "--subject", "--reply", "--replyTo", "--session", "--board", "--limit", "--after", "--timeout", "--id"]);
+
+// Comma-separated recipients: `--to alice,bob,carol` fans out one DM per
+// recipient (same body/subject, unique id each). Keeps the DM-only model
+// while covering "assign N agents" in a single call.
+function parseRecipients(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") {
+    fail(`missing --to <agent-name> (recipient); or comma-separate for broadcast: --to alice,bob,carol`);
+  }
+  const out = [];
+  for (const part of String(raw).split(",")) {
+    if (part.trim() === "") continue;
+    const clean = sanitizeName(part, "recipient");
+    if (!out.includes(clean)) out.push(clean);
+  }
+  if (out.length === 0) fail(`missing --to <agent-name> (recipient)`);
+  if (out.length > 20) fail(`too many recipients (max 20, got ${out.length})`);
+  return out;
+}
+
+function cleanSubject(raw) {
+  if (raw === undefined || raw === null) return undefined;
+  const s = String(raw).trim().slice(0, 120);
+  return s || undefined;
+}
+
+function cleanReply(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return undefined;
+  return String(raw).trim().slice(0, 80);
+}
 function restArgs(args) {
   const out = [];
   for (let i = 0; i < args.length; i++) {
@@ -223,13 +283,22 @@ const OPENCODE_TOOL_DM_SEND = `// .opencode/tools/dm-send.js — primitive DM to
 //
 // Usage from the agent (just a tool call, whenever you want):
 //   dm-send({ from: "alice", to: "bob", body: "the parser accepts ISO dates only" })
+//   dm-send({ from: "lead", to: "alice,bob,carol", subject: "brief: cards", body: "..." })
+//
+// Fanning out work ("assign N agents"): there is no task object — the DM *is*
+// the task. \`to\` accepts a comma list (one copy each, shared batch id); each
+// agent owns its scope and DMs a summary back. Thread answers with \`replyTo\`.
 //
 // What it does:
-//   1. resolves the board (AGENTBOARD_DIR env, else <worktree>/.agentboard)
-//   2. writes .agentboard/dm/<to>/<msg-id>.json (atomic write-then-rename)
+//   1. resolves the board (board arg, AGENTBOARD_DIR env, else walk-up from
+//      worktree/directory/cwd to the project .agentboard)
+//   2. writes .agentboard/dm/<to>/<msg-id>.json per recipient (atomic
+//      write-then-rename, unique id each, shared batch id on fan-out)
 //   3. upserts .agentboard/agents/<from>.json with { lastSeen, sessionId }
 //      so the watcher plugin can route pushes back to the right session.
-//   4. returns "sent <id> -> <to>" for the calling agent to see.
+//   4. stamps the sender's git rev (when inside a checkout) so recipients
+//      can tell whether cited file:line numbers are stale.
+//   5. returns "sent <id> -> <to> [board <path>]" for the calling agent.
 //
 // Delivery ("inserted into context") is done by ../plugins/dm-watch.js, which
 // polls dm/ and injects via client.session.promptAsync. This tool never blocks
@@ -239,17 +308,8 @@ import { tool } from "@opencode-ai/plugin";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
 
-function boardRoot(worktree, override) {
-  if (override) return path.resolve(String(override));
-  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  const base = worktree || process.cwd();
-  return findBoardUpward(base) || path.join(base, ".agentboard");
-}
-
-// Nearest ancestor (incl. start) containing a .agentboard dir, or null.
-// Harnesses sometimes run agents with a cwd below (or beside) the project;
-// walk-up keeps every session on the same board.
 function findBoardUpward(start) {
   let dir = path.resolve(start);
   for (;;) {
@@ -262,6 +322,31 @@ function findBoardUpward(start) {
   }
 }
 
+// Try every base the harness gives us (worktree, directory, cwd): harnesses
+// sometimes run agents with a cwd below (or beside) the project, or with an
+// empty worktree. First walk-up hit wins; otherwise fall back to
+// <primary>/.agentboard so the caller gets the drive-root guard instead of a
+// silent stray board.
+function boardRoot(candidates, override) {
+  if (override) return { root: path.resolve(String(override)), tried: [path.resolve(String(override))] };
+  if (process.env.AGENTBOARD_DIR) return { root: path.resolve(process.env.AGENTBOARD_DIR), tried: [path.resolve(process.env.AGENTBOARD_DIR)] };
+  const tried = [];
+  for (const base of candidates) {
+    if (!base) continue;
+    let dir;
+    try {
+      dir = path.resolve(String(base));
+    } catch {
+      continue;
+    }
+    tried.push(dir);
+    const hit = findBoardUpward(dir);
+    if (hit) return { root: hit, tried };
+  }
+  const primary = path.resolve(String(candidates[0] || process.cwd()));
+  return { root: path.join(primary, ".agentboard"), tried };
+}
+
 function clean(name, what) {
   if (!name) throw new Error("missing " + what);
   const c = String(name).trim().replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
@@ -269,51 +354,122 @@ function clean(name, what) {
   return c;
 }
 
+function parseRecipients(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") {
+    throw new Error("missing to (recipient); or comma-separate for broadcast: alice,bob,carol");
+  }
+  const out = [];
+  for (const part of String(raw).split(",")) {
+    if (part.trim() === "") continue;
+    const c = clean(part, "to");
+    if (!out.includes(c)) out.push(c);
+  }
+  if (out.length === 0) throw new Error("missing to (recipient)");
+  if (out.length > 20) throw new Error(\`too many recipients (max 20, got \${out.length})\`);
+  return out;
+}
+
+function cleanSubject(raw) {
+  if (raw === undefined || raw === null) return undefined;
+  const s = String(raw).trim().slice(0, 120);
+  return s || undefined;
+}
+
+function cleanReply(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return undefined;
+  return String(raw).trim().slice(0, 80);
+}
+
+// Best-effort git rev of the project containing the board. Never throws.
+function gitRev(root) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: path.dirname(root),
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+    return String(out).trim().slice(0, 40) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function writeJsonAtomic(p, obj) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  const tmp = p + "." + process.pid + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\\n");
-  fs.renameSync(tmp, p);
+  try {
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    const start = Date.now();
+    while (Date.now() - start < 50) { /* brief spin for Windows AV holds */ }
+    try {
+      fs.renameSync(tmp, p);
+    } catch (e2) {
+      try { fs.rmSync(tmp, { force: true }); } catch {}
+      throw e2;
+    }
+  }
+}
+
+function newId(prefix) {
+  const t = new Date();
+  const stamp =
+    String(t.getUTCFullYear()).slice(2) +
+    String(t.getUTCMonth() + 1).padStart(2, "0") +
+    String(t.getUTCDate()).padStart(2, "0") +
+    "-" +
+    String(t.getUTCHours()).padStart(2, "0") +
+    String(t.getUTCMinutes()).padStart(2, "0") +
+    String(t.getUTCSeconds()).padStart(2, "0");
+  return \`\${prefix}-\${stamp}-\${crypto.randomBytes(4).toString("hex")}\`;
 }
 
 export default tool({
   description:
-    "Send a direct message to another AI agent via agent-board. Use whenever you want to coordinate, share a finding, or ask a peer. Fire-and-forget like Slack — the peer's session gets it injected into context. Args: from (your stable agent name), to (peer's agent name), body (message text), board (optional absolute board path when your session runs outside the project).",
+    "Send a direct message to another AI agent via agent-board. Use whenever you want to coordinate, share a finding, or ask a peer. Fire-and-forget like Slack — the peer's session gets it injected into context. \`to\` accepts a comma list (broadcast: one copy each, shared batch id) for fanning work out to N agents. Args: from (your stable agent name), to (peer's agent name), body (message text), subject (optional mission line), replyTo (optional msg id you are answering), board (optional absolute board path when your session runs outside the project).",
   args: {
     from: tool.schema.string().describe("Your stable agent name, e.g. alice. Keep it constant for the session."),
-    to: tool.schema.string().describe("Recipient agent name, e.g. bob. They receive it on inbox/listen even before registering."),
+    to: tool.schema.string().describe("Recipient agent name, e.g. bob — or comma list for broadcast: alice,bob,carol. They receive it on inbox/listen even before registering."),
     body: tool.schema.string().describe("Message text, 1..8000 chars."),
+    subject: tool.schema.string().optional().describe("Optional mission line, e.g. 'brief: borderless cards'. Shown above the body."),
+    replyTo: tool.schema.string().optional().describe("Optional message id you are answering (threads the reply)."),
     board: tool.schema.string().optional().describe("Optional absolute board path, e.g. C:/proj/.agentboard. Overrides AGENTBOARD_DIR and auto-detection."),
   },
   async execute(args, context) {
     const from = clean(args.from, "from");
-    const to = clean(args.to, "to");
+    const recipients = parseRecipients(args.to);
     const body = String(args.body || "").trim();
     if (!body) return "error: empty body";
     if (body.length > 8000) return "error: body too large (max 8000 chars)";
+    const subject = cleanSubject(args.subject);
+    const replyTo = cleanReply(args.replyTo);
     const boardArg = args.board === undefined || args.board === null || String(args.board).trim() === "" ? undefined : String(args.board);
-    const root = boardRoot(context.worktree || context.directory || process.cwd(), boardArg);
+    const worktree = context.worktree || context.directory || process.cwd();
+    const { root, tried } = boardRoot([worktree, context.directory, process.cwd()], boardArg);
     if (!boardArg && !process.env.AGENTBOARD_DIR) {
       let exists = false;
       try {
         exists = fs.statSync(root).isDirectory();
       } catch {}
       if (!exists && path.dirname(root) === path.parse(root).root) {
-        return \`error: refusing to create a board at drive root \${root} — pass board (absolute path) or set AGENTBOARD_DIR\`;
+        return \`error: refusing to create a board at drive root \${root} — no project board found. Tried walk-up from: \${tried.join(" | ") || "(nothing)"}. Run from your project (the dir containing .agentboard/), pass board (absolute path to .agentboard), or set AGENTBOARD_DIR.\`;
       }
     }
-    const now = new Date().toISOString();
-    const t = new Date();
-    const stamp =
-      String(t.getUTCFullYear()).slice(2) +
-      String(t.getUTCMonth() + 1).padStart(2, "0") +
-      String(t.getUTCDate()).padStart(2, "0") +
-      "-" +
-      String(t.getUTCHours()).padStart(2, "0") +
-      String(t.getUTCMinutes()).padStart(2, "0") +
-      String(t.getUTCSeconds()).padStart(2, "0");
-    const id = "msg-" + stamp + "-" + crypto.randomBytes(3).toString("hex");
-    writeJsonAtomic(path.join(root, "dm", to, id + ".json"), { id, from, to, body, at: now });
+    const rev = gitRev(root);
+    const at = new Date().toISOString();
+    const batch = recipients.length > 1 ? newId("batch") : undefined;
+    const sent = [];
+    for (const to of recipients) {
+      const id = newId("msg");
+      const msg = { id, from, to, body, at };
+      if (subject) msg.subject = subject;
+      if (replyTo) msg.replyTo = replyTo;
+      if (batch) msg.batch = batch;
+      if (rev) msg.rev = rev;
+      writeJsonAtomic(path.join(root, "dm", to, id + ".json"), msg);
+      sent.push(\`\${id} -> \${to}\`);
+    }
     // upsert sender with live session routing for the watcher plugin
     const ap = path.join(root, "agents", from + ".json");
     let prev = null;
@@ -322,12 +478,13 @@ export default tool({
     } catch {}
     writeJsonAtomic(ap, {
       name: from,
-      firstSeen: (prev && prev.firstSeen) || now,
-      lastSeen: now,
+      firstSeen: (prev && prev.firstSeen) || new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
       sessionId: (context && context.sessionID) || (prev && prev.sessionId) || undefined,
       lastDir: context.worktree || context.directory || undefined,
     });
-    return "sent " + id + " -> " + to + " [board " + root + "]";
+    if (sent.length === 1) return "sent " + sent[0] + " [board " + root + "]";
+    return \`sent \${sent.length} messages [board \${root}]: \${sent.join(", ")}\`;
   },
 });
 `;
@@ -346,6 +503,13 @@ const OPENCODE_PLUGIN_DM_WATCH = `// .opencode/plugins/dm-watch.js — inject DM
 // mixing harnesses never get a message twice.
 // Polls every 1s; that poll is the source of truth (no fs.watch dependency).
 //
+// Delivery is at-least-once: the claim wins the race between watcher
+// instances, but the marker is released (and the cursor left alone) when
+// promptAsync throws — e.g. pushing into a stale session from yesterday
+// fails with \`encrypted_content was not issued to this caller\`. Stale
+// session mappings are then invalidated so mail waits for pull until the
+// live session re-registers, instead of being black-holed as delivered.
+//
 // Agents with no known session are skipped — their mail waits in the inbox
 // for pull (\`inbox --from <you>\`), so one idle session never steals another
 // agent's mail.
@@ -442,6 +606,40 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     }
   }
 
+  // Roll back a claim won above when the push itself fails: remove the
+  // on-disk marker and the in-memory entry so the next poll retries.
+  // The cursor is intentionally left alone here — it only advances on
+  // success, so a failed push never fast-forwards past undelivered mail.
+  function releaseClaim(agent, id) {
+    processed.delete(agent + "/" + id);
+    try {
+      fs.rmSync(deliveredMarker(agent, id), { force: true });
+    } catch {}
+  }
+
+  // promptAsync into a dead session throws provider errors like
+  // "[invalid_request_error] reasoning \`encrypted_content\` was not issued
+  // to this caller". Those mean the routing entry is stale, not the
+  // message — drop the mapping so mail waits for pull (\`inbox\`) until the
+  // live session re-registers via \`register --session\` or \`dm-send\`.
+  function isStaleSessionError(e) {
+    const s = String((e && e.message ? e.message : e) || "");
+    return /encrypted_content|invalid_request_error|unknown session|session not found|no such session|not issued to this caller/i.test(s);
+  }
+
+  function invalidateSession(agent, sessionID) {
+    agentToSession.delete(agent);
+    try {
+      const p = path.join(agentsDir, agent + ".json");
+      const doc = readJsonSafe(p);
+      if (doc && doc.sessionId === sessionID) {
+        delete doc.sessionId;
+        doc.lastSeen = new Date().toISOString();
+        fs.writeFileSync(p, JSON.stringify(doc, null, 2) + "\\n");
+      }
+    } catch {}
+  }
+
   // Cursor file shared with agentboard-hook: hook delivery moves it, and we
   // honor it (plus our markers) so mixed-harness agents never get doubles.
   // We also advance it on our own deliveries.
@@ -485,30 +683,44 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     return curIdx !== -1 && idx !== -1 && idx <= curIdx;
   }
 
+  function formatDm(msg) {
+    let head = "[DM from " + msg.from + " @ " + (msg.at || "unknown time");
+    if (msg.rev) head += \` (rev \${msg.rev})\`;
+    if (msg.batch) head += \` [batch \${msg.batch}]\`;
+    if (msg.replyTo) head += \` re: \${msg.replyTo}\`;
+    head += "]";
+    const subj = msg.subject ? \`subj: \${msg.subject}\\n\` : "";
+    return (
+      head +
+      "\\n" +
+      subj +
+      msg.body +
+      "\\n\\n(Reply with dm-send (replyTo: \\"" +
+      msg.id +
+      "\\") if needed, or continue current work if unrelated. Re-read cited files vs your checkout before flagging — the rev above tells you if the sender's file:line numbers are stale.)"
+    );
+  }
+
   async function deliver(agent, sessionID, msg) {
     if (!claim(agent, msg.id, sessionID)) return;
-    advanceCursor(agent, msg.id);
-    const text =
-      "[DM from " +
-      msg.from +
-      " @ " +
-      msg.at +
-      "]\\n" +
-      msg.body +
-      "\\n\\n(Reply with dm-send if needed, or continue current work if unrelated.)";
+    const text = formatDm(msg);
     try {
       if (client.session && typeof client.session.promptAsync === "function") {
         await client.session.promptAsync({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       } else if (client.session && typeof client.session.prompt === "function") {
         await client.session.prompt({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       }
+      advanceCursor(agent, msg.id);
     } catch (e) {
+      const detail = e && e.message ? e.message : String(e);
+      releaseClaim(agent, msg.id);
+      if (isStaleSessionError(e)) invalidateSession(agent, sessionID);
       try {
         await client.app.log({
           body: {
             service: "dm-watch",
             level: "warn",
-            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+            message: "DM push failed for " + agent + " (" + msg.id + "), released for retry: " + detail,
           },
         });
       } catch {}
@@ -560,6 +772,10 @@ export const DmWatchPlugin = async ({ client, directory }) => {
           from: msg.from,
           body: String(msg.body),
           at: msg.at || "",
+          subject: msg.subject,
+          replyTo: msg.replyTo,
+          batch: msg.batch,
+          rev: msg.rev,
         });
       }
     }
@@ -593,12 +809,20 @@ Binary: \`{CLI}\` (board lives in \`./.agentboard\`, or \`$env:AGENTBOARD_DIR\`)
 
     {CLI} register --from <you> [--session <opencode-session-id>]
     {CLI} agents
-    {CLI} send --from <you> --to <peer> --body "..."   # just a tool call, whenever you want
+    {CLI} send --from <you> --to <peer> --body "..." [--subject "..."] [--reply <msg-id>]
     {CLI} inbox --from <you> [--limit 20] [--after <msg-id>] [--json]
     {CLI} listen --from <you> [--timeout 60000]        # block and print new DMs as they arrive
 
+Fanning out work ("assign N agents"): there is no task object — the DM *is*
+the task. \`--to alice,bob,carol\` sends one copy each (shared batch id),
+each agent owns its scope, decides itself, and DMs a summary back. Use
+\`--subject\` for the mission line, \`--reply <msg-id>\` to thread answers,
+and re-read cited files before flagging (every DM stamps the sender's git
+rev so you can spot stale file:line numbers).
+
 On opencode the \`dm-send\` tool does the same as \`send\` (and registers your session for push).
 Incoming DMs are inserted into your context automatically by the watcher plugin — otherwise poll \`inbox\` often.
+Every send/inbox echoes \`[board <path>]\`: if two agents see different boards, export \`AGENTBOARD_DIR=<board>\` so all sessions share one.
 
 Rules: pick a stable \`--from\` name and keep it. Discover peers via \`agents\`. Send DMs anytime. No tasks, no claims, no holds — emergent coordination.
 <!-- agentboard:end -->
@@ -1018,8 +1242,31 @@ function cmdRegister(args) {
   console.log(`registered ${agent}${doc.sessionId ? ` (session ${doc.sessionId})` : ""} [board ${d.root}]`);
 }
 
+// Read-side commands (agents/inbox/listen) must never plant a board: if the
+// resolved board has no board.json, fail loudly instead of showing an empty
+// room that hides a split-board misconfiguration.
+function requireBoard(root) {
+  let meta = null;
+  try {
+    meta = readJson(path.join(root, "board.json"));
+  } catch {}
+  if (!meta || meta.version !== BOARD_VERSION) {
+    fail(
+      `no board at ${root} (cwd "${process.cwd()}"). ` +
+        `Run from your project (the dir containing .agentboard/), pass --board <absolute path to .agentboard>, or set AGENTBOARD_DIR. ` +
+        `If you just created one elsewhere, every send echoes [board <path>] — point all agents at the same one.`
+    );
+  }
+  const d = dirs(root);
+  for (const p of [d.root, d.agents, d.dm, d.delivered]) {
+    fs.mkdirSync(p, { recursive: true });
+  }
+  return d;
+}
+
 function cmdAgents(args) {
-  const d = ensureBoard(boardDir(args));
+  const root = boardDir(args);
+  const d = requireBoard(root);
   const items = listJson(d.agents)
     .map((e) => e.data)
     .filter((x) => x && x.name)
@@ -1035,6 +1282,7 @@ function cmdAgents(args) {
   for (const a of items) {
     console.log(`${a.name}  (last seen ${relTime(a.lastSeen)}${a.sessionId ? `, session ${a.sessionId}` : ""})`);
   }
+  console.log(`[board ${d.root}]`);
 }
 
 function cmdSend(args) {
@@ -1042,19 +1290,37 @@ function cmdSend(args) {
   refuseDriveRootBoard(root, args);
   const d = ensureBoard(root);
   const from = resolveAgent(args, "sender");
-  const toRaw = getFlag(args, "--to");
-  const to = sanitizeName(toRaw, "recipient");
+  const recipients = parseRecipients(getFlag(args, "--to"));
   const body = getFlag(args, "--body") || restArgs(args).join(" ");
   if (!body || !body.trim()) fail('missing message body (--body "...")');
   if (body.length > MAX_BODY_CHARS) fail(`message body too large (max ${MAX_BODY_CHARS} chars)`);
+  const subject = cleanSubject(getFlag(args, "--subject"));
+  const replyTo = cleanReply(getFlag(args, "--reply"));
   const session = getFlag(args, "--session");
   touchAgent(d, from, { sessionId: session || undefined, lastDir: process.cwd() });
-  const id = newId("msg");
-  const msg = { id, from, to, body: body.trim(), at: new Date().toISOString() };
-  const dir = path.join(d.dm, to);
-  fs.mkdirSync(dir, { recursive: true });
-  writeJson(path.join(dir, `${id}.json`), msg);
-  console.log(`sent ${id} -> ${to} [board ${d.root}]`);
+  const rev = gitRevForBoard(root);
+  const at = new Date().toISOString();
+  // One shared batch id per fan-out so recipients can tell they got the same
+  // brief; each copy keeps a unique message id.
+  const batch = recipients.length > 1 ? newId("batch") : undefined;
+  const sent = [];
+  for (const to of recipients) {
+    const id = newId("msg");
+    const msg = { id, from, to, body: body.trim(), at };
+    if (subject) msg.subject = subject;
+    if (replyTo) msg.replyTo = replyTo;
+    if (batch) msg.batch = batch;
+    if (rev) msg.rev = rev;
+    const dir = path.join(d.dm, to);
+    fs.mkdirSync(dir, { recursive: true });
+    writeJson(path.join(dir, `${id}.json`), msg);
+    sent.push(`${id} -> ${to}`);
+  }
+  if (sent.length === 1) {
+    console.log(`sent ${sent[0]} [board ${d.root}]`);
+  } else {
+    console.log(`sent ${sent.length} messages [board ${d.root}]: ${sent.join(", ")}`);
+  }
 }
 
 function readDMs(d, recipient) {
@@ -1064,12 +1330,23 @@ function readDMs(d, recipient) {
     .sort((a, b) => (String(a.at).localeCompare(String(b.at)) || String(a.id).localeCompare(String(b.id))));
 }
 
+function msgHeader(m, showTo) {
+  const bits = [`from ${m.from}`];
+  if (showTo) bits.push(`-> ${m.to}`);
+  bits.push(relTime(m.at));
+  if (m.rev) bits.push(`rev ${m.rev}`);
+  if (m.replyTo) bits.push(`re: ${m.replyTo}`);
+  if (m.batch) bits.push(`batch ${m.batch}`);
+  return `${m.id}  (${bits.join(", ")})`;
+}
+
 function printMsg(m, showTo, json) {
   if (json) {
     console.log(JSON.stringify(m));
     return;
   }
-  console.log(`${m.id}  (from ${m.from}${showTo ? ` -> ${m.to}` : ""}, ${relTime(m.at)})`);
+  console.log(msgHeader(m, showTo));
+  if (m.subject) console.log(`  subj: ${m.subject}`);
   console.log(`  ${m.body}`);
   console.log("");
 }
@@ -1077,7 +1354,7 @@ function printMsg(m, showTo, json) {
 function cmdInbox(args) {
   const root = boardDir(args);
   refuseDriveRootBoard(root, args);
-  const d = ensureBoard(root);
+  const d = requireBoard(root);
   const showAll = args.includes("--all");
   const limit = Number(getFlag(args, "--limit") || 20);
   const after = getFlag(args, "--after");
@@ -1118,7 +1395,9 @@ function cmdInbox(args) {
     return;
   }
   if (items.length === 0) {
-    console.log(showAll ? "no messages" : `no messages for ${resolveAgent(args, "reader")}`);
+    // Always echo the board so an empty inbox reads as "nothing here" and
+    // not "wrong board": compare with the sender's [board <path>].
+    console.log(showAll ? `no messages [board ${d.root}]` : `no messages for ${resolveAgent(args, "reader")} [board ${d.root}]`);
     return;
   }
   for (const m of items) printMsg(m, showTo, false);
@@ -1127,7 +1406,7 @@ function cmdInbox(args) {
 async function cmdListen(args) {
   const root = boardDir(args);
   refuseDriveRootBoard(root, args);
-  const d = ensureBoard(root);
+  const d = requireBoard(root);
   const agent = resolveAgent(args, "listener");
   const timeoutMs = Number(getFlag(args, "--timeout") || 0);
   const json = args.includes("--json");
@@ -1182,6 +1461,62 @@ async function cmdListen(args) {
   finish();
 }
 
+// ---------------------------------------------------------------------------
+// redeliver: recover mail a dead watcher consumed (claimed + cursor moved,
+// push failed). Clears delivered/<agent>/<id>.json markers and rewinds
+// cursors/<agent>.json so the next poll/push treats the message as fresh.
+// The DM itself is never touched — inbox always shows the full history.
+// ---------------------------------------------------------------------------
+
+function cmdRedeliver(args) {
+  const root = boardDir(args);
+  refuseDriveRootBoard(root, args);
+  const d = requireBoard(root);
+  const agent = resolveAgent(args, "agent");
+  const id = getFlag(args, "--id");
+  const all = args.includes("--all");
+  if (!id && !all) fail('missing --id <msg-id> (or --all to reset every delivery marker)');
+  if (id && all) fail('pass --id <msg-id> or --all, not both');
+  const order = readDMs(d, agent).map((m) => m.id);
+  let ids;
+  if (all) {
+    ids = order.slice();
+    if (ids.length === 0) fail(`no messages for ${agent}`);
+  } else {
+    if (!order.includes(id)) fail(`unknown message "${id}" for ${agent} (check inbox --from ${agent})`);
+    ids = [id];
+  }
+  for (const mid of ids) {
+    try {
+      fs.rmSync(path.join(d.delivered, agent, `${mid}.json`), { force: true });
+    } catch {}
+  }
+  // Rewind the cursor to the message before the earliest redelivered one so
+  // hook polls and the opencode watcher see it as fresh again. If the
+  // earliest redelivered message is the first in the log (or --all), drop
+  // the cursor entirely.
+  const cursorPath = path.join(d.root, "cursors", `${agent}.json`);
+  if (all) {
+    try {
+      fs.rmSync(cursorPath, { force: true });
+    } catch {}
+  } else {
+    const earliest = order.indexOf(ids[0]);
+    if (earliest <= 0) {
+      try {
+        fs.rmSync(cursorPath, { force: true });
+      } catch {}
+    } else {
+      writeJson(cursorPath, { lastId: order[earliest - 1], at: new Date().toISOString() });
+    }
+  }
+  if (ids.length === 1) {
+    console.log(`redelivered ${ids[0]} for ${agent} [board ${d.root}]`);
+  } else {
+    console.log(`redelivered ${ids.length} messages for ${agent} [board ${d.root}]`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // doctor: validate board + harness wiring
 // ---------------------------------------------------------------------------
@@ -1206,6 +1541,15 @@ function cmdDoctor(args) {
   if (meta && meta.version === 2) ok(`board at ${root} (v2)`);
   else no(`board at ${root}`, "run: agentboard init");
 
+  // Split-board visibility: the most common multi-agent failure is two
+  // sessions talking to two boards. Surface the resolution inputs.
+  info(`cwd ${cwd}`);
+  if (process.env.AGENTBOARD_DIR) info(`AGENTBOARD_DIR=${process.env.AGENTBOARD_DIR}`);
+  else info(`AGENTBOARD_DIR unset (walk-up from cwd)`);
+  const rev = gitRevForBoard(root);
+  if (rev) info(`git rev ${rev} (sends stamp this so recipients spot stale file:line)`);
+  else info(`not a git checkout (sends omit rev)`);
+
   let ids = parseHarnessFlag(args);
   if (ids.length === 0) {
     if (meta && Array.isArray(meta.harnesses) && meta.harnesses.length > 0) ids = meta.harnesses.filter((h) => HARNESSES.includes(h));
@@ -1311,18 +1655,28 @@ Identity:
   agentboard agents [--json]
 
 Messaging (primitive — just a tool call, whenever you want):
-  agentboard send --from <you> --to <peer> --body "..." [--session <id>]
+  agentboard send --from <you> --to <peer> --body "..." [--subject "..."] [--reply <msg-id>] [--session <id>]
+    (--to accepts a comma list for broadcast: --to alice,bob,carol — one DM
+     each, same brief, shared batch id. Replies quote with --reply <msg-id>.
+     Every send stamps the sender's git rev so recipients can spot stale
+     file:line numbers.)
   agentboard inbox --from <you> [--limit 20] [--after <msg-id>] [--all] [--json]
   agentboard listen --from <you> [--timeout <ms>] [--json]
     (prints backlog, then blocks and prints new DMs as they arrive;
      opencode plugin injects into context automatically instead of polling)
+  agentboard redeliver --from <you> (--id <msg-id> | --all)
+    (recover mail a dead watcher consumed: clears delivered markers and
+     rewinds the cursor so the next poll/push treats it as fresh;
+     use after re-registering with the live session)
 
   agentboard doctor [--harness <list>] [--board <path>]
     (validate board + harness wiring; exit 1 with FAIL lines when broken)
 
 Tips:
   set AGENTBOARD_AGENT=<name> to skip --from on every command
-  set AGENTBOARD_DIR=<path> (or --board <path>) to pick the board`;
+  set AGENTBOARD_DIR=<path> (or --board <path>) to pick the board
+  every send/inbox echoes [board <path>] — if two agents see different
+  boards, point them at the same one`;
 
 async function main() {
   const [, , cmd, ...rest] = process.argv;
@@ -1336,6 +1690,7 @@ async function main() {
     case "send": return cmdSend(rest);
     case "inbox": return cmdInbox(rest);
     case "listen": return await cmdListen(rest);
+    case "redeliver": return cmdRedeliver(rest);
     case "doctor": return cmdDoctor(rest);
     case undefined:
     case "-h":