@eamonpluto/agentboard 2.2.0 → 2.4.0

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;
@@ -47,7 +48,60 @@ function boardDir(args) {
     return path.join(os.homedir(), ".agentboard", "boards", "default");
   }
   if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(process.cwd(), ".agentboard");
+  // init always plants a board where you stand; every other command walks up
+  // so agents running from a subdirectory land on the project board instead
+  // of silently creating a stray one.
+  if (process.argv[2] === "init") return path.join(process.cwd(), ".agentboard");
+  return findBoardUpward(process.cwd()) || path.join(process.cwd(), ".agentboard");
+}
+
+// Nearest ancestor (incl. start) containing a .agentboard dir, or null.
+function findBoardUpward(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    try {
+      if (fs.statSync(path.join(dir, ".agentboard")).isDirectory()) return path.join(dir, ".agentboard");
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Never silently plant a board at a drive root (e.g. C:\.agentboard): that
+// means cwd resolution failed (detached harness worktree). Fail loudly so
+// the agent sets --board/AGENTBOARD_DIR instead of talking to a stray board.
+function isExplicitBoard(args) {
+  return args.includes("--board") || args.includes("--global") || !!process.env.AGENTBOARD_DIR;
+}
+
+function refuseDriveRootBoard(root, args) {
+  if (isExplicitBoard(args)) return;
+  let exists = false;
+  try {
+    exists = fs.statSync(root).isDirectory();
+  } 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 "${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) {
@@ -79,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. */
@@ -106,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) {
@@ -123,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", "--session", "--board", "--limit", "--after", "--timeout"]);
+
+// 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++) {
@@ -185,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
@@ -201,10 +308,43 @@ 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) {
-  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(worktree, ".agentboard");
+function findBoardUpward(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    try {
+      if (fs.statSync(path.join(dir, ".agentboard")).isDirectory()) return path.join(dir, ".agentboard");
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// 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) {
@@ -214,40 +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).",
+    "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 root = boardRoot(context.worktree || context.directory || process.cwd());
-    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 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 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} — 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 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;
@@ -256,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;
+    if (sent.length === 1) return "sent " + sent[0] + " [board " + root + "]";
+    return \`sent \${sent.length} messages [board \${root}]: \${sent.join(", ")}\`;
   },
 });
 `;
@@ -291,7 +514,20 @@ const POLL_MS = 1000;
 
 function boardRoot(directory) {
   if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
-  return path.join(directory, ".agentboard");
+  return findBoardUpward(directory) || path.join(directory, ".agentboard");
+}
+
+// Nearest ancestor (incl. start) containing a .agentboard dir, or null.
+function findBoardUpward(start) {
+  let dir = path.resolve(start);
+  for (;;) {
+    try {
+      if (fs.statSync(path.join(dir, ".agentboard")).isDirectory()) return path.join(dir, ".agentboard");
+    } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
 }
 
 function readJsonSafe(p) {
@@ -406,17 +642,28 @@ 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 }] } });
@@ -481,6 +728,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,
         });
       }
     }
@@ -514,12 +765,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 -->
@@ -734,7 +993,8 @@ function mergeMcpServers(file, entry) {
 const HARNESS_SECTIONS = {
   opencode: (cli) =>
     `On opencode prefer the \`dm-send\` tool over \`${cli} send\` (same thing, plus it registers your session for push).\n` +
-    `Incoming DMs are inserted into your context automatically by the dm-watch plugin. Restart opencode after \`init\` so the tool + plugin load.`,
+    `Incoming DMs are inserted into your context automatically by the dm-watch plugin. Restart opencode after \`init\` so the tool + plugin load.\n` +
+    `Every send echoes its board (\`[board <path>]\`): if two agents see different boards, export \`AGENTBOARD_DIR=<board>\` so all sessions share one.`,
   claude: (cli) =>
     `On Claude Code use the \`agentboard\` MCP tools (\`dm_send\` / \`dm_inbox\` / \`dm_agents\` / \`dm_register\`) — approve \`.mcp.json\` when prompted.\n` +
     `A Stop hook (\`.claude/settings.json\`) injects waiting DMs at turn end. Set \`AGENTBOARD_AGENT=<you>\` once per terminal so hooks know who you are.`,
@@ -929,15 +1189,40 @@ function touchAgent(d, name, extra) {
 }
 
 function cmdRegister(args) {
-  const d = ensureBoard(boardDir(args));
+  const root = boardDir(args);
+  refuseDriveRootBoard(root, args);
+  const d = ensureBoard(root);
   const agent = resolveAgent(args, "agent");
   const session = getFlag(args, "--session");
   const doc = touchAgent(d, agent, { sessionId: session || undefined, lastDir: process.cwd() });
-  console.log(`registered ${agent}${doc.sessionId ? ` (session ${doc.sessionId})` : ""}`);
+  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)
@@ -953,24 +1238,45 @@ 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) {
-  const d = ensureBoard(boardDir(args));
+  const root = boardDir(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}`);
+  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) {
@@ -980,18 +1286,31 @@ 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("");
 }
 
 function cmdInbox(args) {
-  const d = ensureBoard(boardDir(args));
+  const root = boardDir(args);
+  refuseDriveRootBoard(root, args);
+  const d = requireBoard(root);
   const showAll = args.includes("--all");
   const limit = Number(getFlag(args, "--limit") || 20);
   const after = getFlag(args, "--after");
@@ -1032,14 +1351,18 @@ 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);
 }
 
 async function cmdListen(args) {
-  const d = ensureBoard(boardDir(args));
+  const root = boardDir(args);
+  refuseDriveRootBoard(root, args);
+  const d = requireBoard(root);
   const agent = resolveAgent(args, "listener");
   const timeoutMs = Number(getFlag(args, "--timeout") || 0);
   const json = args.includes("--json");
@@ -1118,6 +1441,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));
@@ -1223,7 +1555,11 @@ 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;
@@ -1234,7 +1570,9 @@ Messaging (primitive — just a tool call, whenever you want):
 
 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;