@eamonpluto/agentboard 2.2.0

package/bin/agentboard.js

@@ -0,0 +1,1265 @@
+#!/usr/bin/env node
+/**
+ * agentboard — DM-only minimal message bus for AI coding agents.
+ *
+ * v2: destructive strip-down to the primitive described as "message another
+ * agent, inserted into context, just a tool call, whenever it wants".
+ *
+ * Storage layout (default: <project>/.agentboard/, override with
+ * AGENTBOARD_DIR or --board <path>):
+ *
+ *   .agentboard/
+ *     board.json               board metadata {name, version:2, createdAt}
+ *     agents/<name>.json       {name, firstSeen, lastSeen, sessionId?, lastDir?}
+ *     dm/<recipient>/<id>.json {id, from, to, body, at}
+ *     delivered/<recipient>/<id>.json  push markers written by the opencode
+ *                                      plugin after injecting into a session
+ *                                      (fire-once; CLI never writes these)
+ *
+ * No tasks, no claims, no holds, no verify gates, no cooldowns. Send whenever
+ * you want. Delivery is files; "inserted into context" is done by the opencode
+ * plugin (opencode/plugins/dm-watch.js) via client.session.promptAsync, or by
+ * polling `inbox` / blocking `listen` on other harnesses.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const MAX_BODY_CHARS = 8000;
+const BOARD_VERSION = 2;
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function fail(msg, code = 1) {
+  process.stderr.write(`agentboard: ${msg}\n`);
+  process.exit(code);
+}
+
+function boardDir(args) {
+  const flagIdx = args.indexOf("--board");
+  if (flagIdx !== -1 && args[flagIdx + 1] && !args[flagIdx + 1].startsWith("--"))
+    return path.resolve(args[flagIdx + 1]);
+  if (args.includes("--global")) {
+    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");
+}
+
+function dirs(root) {
+  return {
+    root,
+    agents: path.join(root, "agents"),
+    dm: path.join(root, "dm"),
+    delivered: path.join(root, "delivered"),
+  };
+}
+
+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");
+  if (!fs.existsSync(metaPath)) {
+    fs.writeFileSync(
+      metaPath,
+      JSON.stringify({ name: "board", version: BOARD_VERSION, createdAt: new Date().toISOString() }, null, 2) + "\n"
+    );
+  }
+  return d;
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+function writeJson(p, obj) {
+  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+
+/** Atomic fire-once claim: create file only if it does not exist. */
+function writeExclusiveJson(p, obj) {
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n", { flag: "wx" });
+    return true;
+  } catch (e) {
+    if (e && (e.code === "EEXIST" || String(e.message).includes("EEXIST"))) return false;
+    throw e;
+  }
+}
+
+function newId(prefix) {
+  const t = new Date();
+  const stamp =
+    t.getUTCFullYear().toString().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(3).toString("hex")}`;
+}
+
+function sanitizeName(name, what) {
+  if (!name) fail(`missing --${what === "recipient" ? "to" : "from"} <agent-name> (${what}); or set env AGENTBOARD_AGENT=<name>`);
+  const clean = String(name).trim().replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 40);
+  if (!clean) fail(`invalid agent name`);
+  return clean;
+}
+
+function getFlag(args, flag) {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] !== undefined && !String(args[i + 1]).startsWith("--") ? args[i + 1] : undefined;
+}
+
+// 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"]);
+function restArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (String(args[i]).startsWith("--")) {
+      if (VALUE_FLAGS.has(args[i])) i++; // skip its value too
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
+function resolveAgent(args, what) {
+  return sanitizeName(getFlag(args, "--from") || process.env.AGENTBOARD_AGENT, what);
+}
+
+function optionalAgent(args) {
+  const raw = getFlag(args, "--from") || process.env.AGENTBOARD_AGENT;
+  return raw ? sanitizeName(raw, "agent") : null;
+}
+
+function listJson(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  return fs
+    .readdirSync(dirPath)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((f) => {
+      const p = path.join(dirPath, f);
+      try {
+        return { file: f, path: p, data: readJson(p) };
+      } catch (e) {
+        return { file: f, path: p, data: { _error: String(e) } };
+      }
+    });
+}
+
+function relTime(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  return `${Math.floor(Math.max(s, 0) / 3600)}h ago`;
+}
+
+function cliInvoke() {
+  const here = path.resolve(process.argv[1] || "").split(path.sep).join("/");
+  if (here.includes("node_modules/agentboard/bin/agentboard.js")) return "agentboard";
+  return `node "${here}"`;
+}
+
+// ---------------------------------------------------------------------------
+// opencode integration templates (embedded so `init` works when globally installed)
+// ---------------------------------------------------------------------------
+
+const OPENCODE_TOOL_DM_SEND = `// .opencode/tools/dm-send.js — primitive DM tool for agent-board (DM-only v2).
+// Filename becomes the tool name: dm-send.
+// Loaded by opencode alongside built-in tools. Zero extra deps.
+//
+// Usage from the agent (just a tool call, whenever you want):
+//   dm-send({ from: "alice", to: "bob", body: "the parser accepts ISO dates only" })
+//
+// 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)
+//   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.
+//
+// Delivery ("inserted into context") is done by ../plugins/dm-watch.js, which
+// polls dm/ and injects via client.session.promptAsync. This tool never blocks
+// waiting for a reply — fire and forget, like Slack.
+
+import { tool } from "@opencode-ai/plugin";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+function boardRoot(worktree) {
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(worktree, ".agentboard");
+}
+
+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);
+  if (!c) throw new Error("invalid " + what);
+  return c;
+}
+
+function writeJsonAtomic(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = p + "." + crypto.randomBytes(4).toString("hex") + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\\n");
+  fs.renameSync(tmp, p);
+}
+
+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).",
+  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."),
+    body: tool.schema.string().describe("Message text, 1..8000 chars."),
+  },
+  async execute(args, context) {
+    const from = clean(args.from, "from");
+    const to = clean(args.to, "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 });
+    // upsert sender with live session routing for the watcher plugin
+    const ap = path.join(root, "agents", from + ".json");
+    let prev = null;
+    try {
+      prev = JSON.parse(fs.readFileSync(ap, "utf8"));
+    } catch {}
+    writeJsonAtomic(ap, {
+      name: from,
+      firstSeen: (prev && prev.firstSeen) || now,
+      lastSeen: now,
+      sessionId: (context && context.sessionID) || (prev && prev.sessionId) || undefined,
+      lastDir: context.worktree || context.directory || undefined,
+    });
+    return "sent " + id + " -> " + to;
+  },
+});
+`;
+
+const OPENCODE_PLUGIN_DM_WATCH = `// .opencode/plugins/dm-watch.js — inject DMs into context (agent-board DM-only v2).
+// Watches <board>/dm/<agent>/*.json and delivers new messages to the live
+// opencode session registered for <agent> via client.session.promptAsync.
+//
+// Routing: .agentboard/agents/<name>.json holds { sessionId }. The dm-send
+// tool writes it on every send; register --session writes it from the CLI.
+// Fire-once: in-memory Set + on-disk delivered/<agent>/<msgId>.json markers
+// claimed with exclusive create ('wx'), pre-populated on startup (survives
+// restarts, same idea as bgrun's .notify -> .notified rename). Markers are
+// shared with agentboard-hook, and the hook's cursors/<agent>.json fast-
+// forward pointer is honored (and advanced on our deliveries), so agents
+// mixing harnesses never get a message twice.
+// Polls every 1s; that poll is the source of truth (no fs.watch dependency).
+//
+// 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.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const POLL_MS = 1000;
+
+function boardRoot(directory) {
+  if (process.env.AGENTBOARD_DIR) return path.resolve(process.env.AGENTBOARD_DIR);
+  return path.join(directory, ".agentboard");
+}
+
+function readJsonSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export const DmWatchPlugin = async ({ client, directory }) => {
+  const root = boardRoot(directory);
+  const dmDir = path.join(root, "dm");
+  const agentsDir = path.join(root, "agents");
+  const deliveredDir = path.join(root, "delivered");
+
+  const agentToSession = new Map(); // agent -> sessionID
+  const processed = new Set(); // "<agent>/<msgId>"
+
+  try {
+    fs.mkdirSync(deliveredDir, { recursive: true });
+  } catch {}
+
+  // pre-populate from delivered markers so restarts don't replay
+  try {
+    for (const agent of fs.readdirSync(deliveredDir)) {
+      const ad = path.join(deliveredDir, agent);
+      try {
+        if (!fs.statSync(ad).isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      for (const f of fs.readdirSync(ad)) {
+        if (f.endsWith(".json")) processed.add(agent + "/" + f.replace(/\\.json$/, ""));
+      }
+    }
+  } catch {}
+
+  function refreshAgentMap() {
+    let files = [];
+    try {
+      files = fs.readdirSync(agentsDir);
+    } catch {
+      return;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue;
+      const doc = readJsonSafe(path.join(agentsDir, f));
+      if (doc && doc.name && doc.sessionId) agentToSession.set(doc.name, doc.sessionId);
+    }
+  }
+
+  function deliveredMarker(agent, id) {
+    return path.join(deliveredDir, agent, id + ".json");
+  }
+
+  function claim(agent, id, sessionID) {
+    const key = agent + "/" + id;
+    if (processed.has(key)) return false;
+    processed.add(key);
+    try {
+      fs.mkdirSync(path.dirname(deliveredMarker(agent, id)), { recursive: true });
+      fs.writeFileSync(deliveredMarker(agent, id), JSON.stringify({ sessionID, at: new Date().toISOString() }) + "\\n", {
+        flag: "wx",
+      });
+      return true;
+    } catch {
+      return false; // already delivered by another instance
+    }
+  }
+
+  // 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.
+  function readCursor(agent) {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(root, "cursors", agent + ".json"), "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  function orderIds(agent) {
+    try {
+      return fs.readdirSync(path.join(dmDir, agent)).filter((f) => f.endsWith(".json")).sort().map((f) => f.replace(/\\.json$/, ""));
+    } catch {
+      return [];
+    }
+  }
+
+  function advanceCursor(agent, id) {
+    try {
+      const order = orderIds(agent);
+      const cur = readCursor(agent);
+      const curIdx = cur && cur.lastId ? order.indexOf(cur.lastId) : -1;
+      if (order.indexOf(id) > curIdx) {
+        fs.mkdirSync(path.join(root, "cursors"), { recursive: true });
+        fs.writeFileSync(
+          path.join(root, "cursors", agent + ".json"),
+          JSON.stringify({ lastId: id, at: new Date().toISOString() }) + "\\n"
+        );
+      }
+    } catch {}
+  }
+
+  function coveredByCursor(agent, id) {
+    const order = orderIds(agent);
+    const cur = readCursor(agent);
+    if (!cur || !cur.lastId) return false;
+    const curIdx = order.indexOf(cur.lastId);
+    const idx = order.indexOf(id);
+    return curIdx !== -1 && idx !== -1 && idx <= curIdx;
+  }
+
+  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.)";
+    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 }] } });
+      }
+    } catch (e) {
+      try {
+        await client.app.log({
+          body: {
+            service: "dm-watch",
+            level: "warn",
+            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+          },
+        });
+      } catch {}
+    }
+  }
+
+  async function poll() {
+    refreshAgentMap();
+    let agents = [];
+    try {
+      agents = fs.readdirSync(dmDir).filter((e) => {
+        try {
+          return fs.statSync(path.join(dmDir, e)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+    } catch {
+      return;
+    }
+    for (const agent of agents) {
+      const sessionID = agentToSession.get(agent);
+      if (!sessionID) continue; // nobody live for this name — mail waits for pull
+      let files = [];
+      try {
+        files = fs.readdirSync(path.join(dmDir, agent)).filter((f) => f.endsWith(".json")).sort();
+      } catch {
+        continue;
+      }
+      for (const f of files) {
+        const id = f.replace(/\\.json$/, "");
+        const key = agent + "/" + id;
+        if (processed.has(key)) continue;
+        if (fs.existsSync(deliveredMarker(agent, id))) {
+          processed.add(key);
+          continue;
+        }
+        if (coveredByCursor(agent, id)) {
+          processed.add(key);
+          continue;
+        }
+        const msg = readJsonSafe(path.join(dmDir, agent, f));
+        if (!msg || !msg.id || !msg.from || !msg.body) {
+          processed.add(key);
+          continue;
+        }
+        await deliver(agent, agentToSession.get(agent) || sessionID, {
+          id: msg.id,
+          from: msg.from,
+          body: String(msg.body),
+          at: msg.at || "",
+        });
+      }
+    }
+  }
+
+  const timer = setInterval(() => {
+    poll().catch(() => {});
+  }, POLL_MS);
+  poll().catch(() => {});
+
+  return {
+    dispose: async () => {
+      clearInterval(timer);
+    },
+  };
+};
+
+export default DmWatchPlugin;
+`;
+
+// ---------------------------------------------------------------------------
+// AGENTS.md snippet (minimal)
+// ---------------------------------------------------------------------------
+
+const AGENTS_MD_SNIPPET = `<!-- agentboard:start -->
+## Agent board (DM-only)
+
+You coordinate with other AI agents by messaging them directly — like Slack, minimal structure, figure it out yourselves.
+
+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} inbox --from <you> [--limit 20] [--after <msg-id>] [--json]
+    {CLI} listen --from <you> [--timeout 60000]        # block and print new DMs as they arrive
+
+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.
+
+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 -->
+`;
+
+function upsertAgentsMd(cwd, snippet) {
+  const agentsMd = path.join(cwd, "AGENTS.md");
+  if (!fs.existsSync(agentsMd)) {
+    fs.writeFileSync(agentsMd, `# AGENTS.md\n\n` + snippet);
+    console.log("Created AGENTS.md with agent-board DM instructions");
+    return;
+  }
+  let cur = fs.readFileSync(agentsMd, "utf8");
+  const start = "<!-- agentboard:start -->";
+  const end = "<!-- agentboard:end -->";
+  if (cur.includes(start) && cur.includes(end)) {
+    const re = new RegExp("<!-- agentboard:start -->[\\s\\S]*?<!-- agentboard:end -->", "m");
+    cur = cur.replace(re, snippet.trim());
+    fs.writeFileSync(agentsMd, cur.endsWith("\n") ? cur : cur + "\n");
+    console.log("Updated agent-board section in AGENTS.md");
+    return;
+  }
+  // Remove legacy v1 block if present (it starts with "## Agent board" and mentions the old workflow)
+  if (cur.includes("COORDINATOR PRIME DIRECTIVE") || cur.includes("tasks ready")) {
+    const lines = cur.split("\n");
+    const out = [];
+    let skipping = false;
+    for (const ln of lines) {
+      if (/^## Agent board/.test(ln)) { skipping = true; continue; }
+      if (skipping && /^## /.test(ln)) { skipping = false; }
+      if (!skipping) out.push(ln);
+    }
+    cur = out.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+    fs.writeFileSync(agentsMd, cur);
+    console.log("Removed legacy agent-board v1 section from AGENTS.md");
+    cur = fs.readFileSync(agentsMd, "utf8");
+  }
+  if (!cur.includes("agentboard") && !cur.includes("agent-board DM")) {
+    fs.appendFileSync(agentsMd, "\n" + snippet);
+    console.log("Appended agent-board DM section to AGENTS.md");
+  } else if (!cur.includes(start)) {
+    fs.appendFileSync(agentsMd, "\n" + snippet);
+    console.log("Appended agent-board DM section to AGENTS.md");
+  }
+}
+
+function installOpencodeFiles(cwd, force) {
+  const toolsDir = path.join(cwd, ".opencode", "tools");
+  const pluginsDir = path.join(cwd, ".opencode", "plugins");
+  fs.mkdirSync(toolsDir, { recursive: true });
+  fs.mkdirSync(pluginsDir, { recursive: true });
+  const toolPath = path.join(toolsDir, "dm-send.js");
+  const pluginPath = path.join(pluginsDir, "dm-watch.js");
+  // Prefer repo-shipped templates when running from a checkout (keeps CLI embed in sync).
+  let toolSrc = OPENCODE_TOOL_DM_SEND;
+  let pluginSrc = OPENCODE_PLUGIN_DM_WATCH;
+  try {
+    const here = path.dirname(path.resolve(process.argv[1] || ""));
+    const repoTool = path.join(here, "..", "opencode", "tools", "dm-send.js");
+    const repoPlugin = path.join(here, "..", "opencode", "plugins", "dm-watch.js");
+    if (fs.existsSync(repoTool)) toolSrc = fs.readFileSync(repoTool, "utf8");
+    if (fs.existsSync(repoPlugin)) pluginSrc = fs.readFileSync(repoPlugin, "utf8");
+  } catch {}
+  let wrote = 0;
+  if (!fs.existsSync(toolPath) || force) {
+    fs.writeFileSync(toolPath, toolSrc);
+    console.log(`Installed opencode tool: ${toolPath}`);
+    wrote++;
+  } else {
+    console.log(`opencode tool exists, skipping (use --force to overwrite): ${toolPath}`);
+  }
+  if (!fs.existsSync(pluginPath) || force) {
+    fs.writeFileSync(pluginPath, pluginSrc);
+    console.log(`Installed opencode plugin: ${pluginPath}`);
+    wrote++;
+  } else {
+    console.log(`opencode plugin exists, skipping (use --force to overwrite): ${pluginPath}`);
+  }
+  return wrote;
+}
+
+// ---------------------------------------------------------------------------
+// harness adapters (init --harness)
+// ---------------------------------------------------------------------------
+// The dm/ file protocol is identical on every harness. What differs is the
+// wiring init installs: hooks files, MCP config, and AGENTS.md wording.
+// Explicit --harness wins; otherwise init applies the union of detected
+// marker dirs (.opencode/.claude/.codex/.agents/.grok). No markers at all
+// keeps the legacy default (opencode) so existing checkouts don't change.
+
+const HARNESSES = ["opencode", "claude", "codex", "antigravity", "grok", "generic"];
+const HARNESS_MARKERS = {
+  opencode: ".opencode",
+  claude: ".claude",
+  codex: ".codex",
+  antigravity: ".agents",
+  grok: ".grok",
+};
+
+function parseHarnessFlag(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--harness" && args[i + 1] && !String(args[i + 1]).startsWith("--")) {
+      for (const part of String(args[i + 1]).split(",")) {
+        const h = part.trim().toLowerCase();
+        if (!h) continue;
+        if (!HARNESSES.includes(h)) fail(`unknown --harness "${part}" (want one of ${HARNESSES.join("|")})`);
+        if (!out.includes(h)) out.push(h);
+      }
+    }
+  }
+  return out;
+}
+
+function detectHarnesses(cwd) {
+  const found = [];
+  for (const [h, marker] of Object.entries(HARNESS_MARKERS)) {
+    try {
+      if (fs.statSync(path.join(cwd, marker)).isDirectory() && !found.includes(h)) found.push(h);
+    } catch {}
+  }
+  return found;
+}
+
+function binAbs(name) {
+  let here = "";
+  try {
+    here = path.dirname(fs.realpathSync(path.resolve(process.argv[1] || "")));
+  } catch {
+    here = path.dirname(path.resolve(process.argv[1] || ""));
+  }
+  return path.join(here, name).split(path.sep).join("/");
+}
+
+function readJsonFile(p, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function hookCommand(hookAbs, sub, extra) {
+  return `node "${hookAbs}" ${sub}${extra ? ` ${extra}` : ""}`;
+}
+
+// Merge Claude/Codex style {hooks:{Event:[groups]}}: append our group per
+// event unless a group already references agentboard-hook. Returns changed?
+function mergeHookGroups(file, hookAbs, boardExtra, styles) {
+  const obj = readJsonFile(file, {});
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    fail(`cannot merge hooks: ${file} is not a JSON object (edit it by hand)`);
+  }
+  obj.hooks = obj.hooks && typeof obj.hooks === "object" ? obj.hooks : {};
+  let changed = false;
+  for (const [event, style] of Object.entries(styles)) {
+    const groups = Array.isArray(obj.hooks[event]) ? obj.hooks[event] : [];
+    const hasOurs = groups.some((g) =>
+      (g && g.hooks && g.hooks.some((h) => String((h && h.command) || "").includes("agentboard-hook")))
+    );
+    if (!hasOurs) {
+      const sub = event === "SessionStart" ? "session-start" : `poll --style ${style}`;
+      groups.push({ hooks: [{ type: "command", command: hookCommand(hookAbs, sub, boardExtra) }] });
+      changed = true;
+    }
+    obj.hooks[event] = groups;
+  }
+  if (changed) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJson(file, obj);
+  }
+  return changed;
+}
+
+// Merge Antigravity style {name: {Event: [...]}} under our own key. Returns changed?
+function mergeAntigravityHooks(file, hookAbs, boardExtra) {
+  const obj = readJsonFile(file, {});
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    fail(`cannot merge hooks: ${file} is not a JSON object (edit it by hand)`);
+  }
+  const stop = hookCommand(hookAbs, "poll --style antigravity-stop", boardExtra);
+  const pre = hookCommand(hookAbs, "poll --style antigravity-pre --idle-after 30", boardExtra);
+  const want = {
+    Stop: [{ hooks: [{ type: "command", command: stop, timeout: 30 }] }],
+    PreInvocation: [{ type: "command", command: pre, timeout: 30 }],
+  };
+  if (JSON.stringify(obj["agentboard-dm"]) !== JSON.stringify(want)) {
+    obj["agentboard-dm"] = want;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJson(file, obj);
+    return true;
+  }
+  return false;
+}
+
+// Merge {mcpServers:{agentboard: entry}} (Claude .mcp.json, Antigravity mcp_config.json). Returns changed?
+function mergeMcpServers(file, entry) {
+  const obj = readJsonFile(file, {});
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    fail(`cannot merge MCP config: ${file} is not a JSON object (edit it by hand)`);
+  }
+  obj.mcpServers = obj.mcpServers && typeof obj.mcpServers === "object" ? obj.mcpServers : {};
+  if (JSON.stringify(obj.mcpServers.agentboard) !== JSON.stringify(entry)) {
+    obj.mcpServers.agentboard = entry;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeJson(file, obj);
+    return true;
+  }
+  return false;
+}
+
+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.`,
+  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.`,
+  codex: (cli) =>
+    `On Codex run \`codex mcp add agentboard -- node "<abs path to>/bin/agentboard-mcp.js"\` for the \`dm_send\`/\`dm_inbox\` tools,\n` +
+    `then open \`/hooks\` and trust the project hooks. A Stop hook (\`.codex/hooks.json\`) injects waiting DMs at turn end. Set \`AGENTBOARD_AGENT=<you>\` once per terminal.`,
+  antigravity: (cli) =>
+    `On Antigravity the \`agentboard\` MCP server (\`.agents/mcp_config.json\`) gives you DM tools; Stop/PreInvocation hooks (\`.agents/hooks.json\`) inject waiting DMs.\n` +
+    `Set \`AGENTBOARD_AGENT=<you>\` once per terminal so hooks know who you are.`,
+  grok: (cli) =>
+    `On grok-build run \`grok mcp add --scope project agentboard -- node "<abs path to>/bin/agentboard-mcp.js"\` for the DM tools,\n` +
+    `then grant folder trust (\`/hooks-trust\`) so the project hooks in \`.grok/hooks/\` run. A Stop hook injects waiting DMs at turn end (Claude-compatible envelope).\n` +
+    `\`AGENTS.md\` is auto-loaded (needs the same folder trust). Set \`AGENTBOARD_AGENT=<you>\` once per terminal.`,
+  generic: (cli) =>
+    `On any other harness: send with \`${cli} send\`, read with \`inbox\`, or block with \`listen\`. Poll \`inbox\` at session start and after each task.`,
+};
+
+function upsertHarnessSections(cwd, cli, ids) {
+  const agentsMd = path.join(cwd, "AGENTS.md");
+  if (!fs.existsSync(agentsMd)) return;
+  let cur = fs.readFileSync(agentsMd, "utf8");
+  cur = cur.replace(/<!-- agentboard:harness:.*?-->[\s\S]*?<!-- agentboard:harness:.*?end -->\n?/g, "");
+  const blocks = ids
+    .filter((h) => HARNESS_SECTIONS[h])
+    .map((h) => `<!-- agentboard:harness:${h} -->\n${HARNESS_SECTIONS[h](cli)}\n<!-- agentboard:harness:${h}:end -->`);
+  if (blocks.length > 0) {
+    cur = cur.endsWith("\n") ? cur : cur + "\n";
+    cur += "\n" + blocks.join("\n\n") + "\n";
+  }
+  fs.writeFileSync(agentsMd, cur);
+  console.log(`AGENTS.md harness notes: ${ids.join(", ") || "none"}`);
+}
+
+function recordHarnesses(root, ids) {
+  const p = path.join(root, "board.json");
+  const meta = readJsonFile(p, {});
+  meta.harnesses = ids;
+  try {
+    writeJson(p, meta);
+  } catch {}
+}
+
+function mcpEntry(ctx, mcpAbs) {
+  // --portable writes PATH-based entries (needs npm i -g . first); default
+  // writes absolute paths that work from a checkout with zero setup.
+  if (ctx.portable) {
+    const entry = { command: "agentboard-mcp", args: [] };
+    if (ctx.mcpEnv) entry.env = ctx.mcpEnv;
+    return entry;
+  }
+  const entry = { command: "node", args: [mcpAbs] };
+  if (ctx.mcpEnv) entry.env = ctx.mcpEnv;
+  return entry;
+}
+
+function mcpRunCmd(ctx, mcpAbs, tool) {
+  // one-liner the user runs for harnesses whose MCP lives outside the repo
+  // (codex/grok keep MCP in user config, so init prints instead of writing)
+  const run = ctx.portable ? "agentboard-mcp" : `node "${mcpAbs}"`;
+  if (tool === "grok") return `grok mcp add --scope project agentboard -- ${run}`;
+  return `${tool} mcp add agentboard -- ${run}`;
+}
+
+function applyHarness(cwd, h, ctx) {
+  const { force, hookAbs, mcpAbs, boardExtra, mcpEnv } = ctx;
+  switch (h) {
+    case "opencode":
+      installOpencodeFiles(cwd, force);
+      return [];
+    case "claude": {
+      const changedHooks = mergeHookGroups(path.join(cwd, ".claude", "settings.json"), hookAbs, boardExtra, {
+        SessionStart: "session-start",
+        Stop: "claude",
+      });
+      console.log(changedHooks ? "Wired Claude hooks: .claude/settings.json (SessionStart + Stop)" : "Claude hooks already wired: .claude/settings.json");
+      const entry = mcpEntry(ctx, mcpAbs);
+      const changedMcp = mergeMcpServers(path.join(cwd, ".mcp.json"), entry);
+      console.log(changedMcp ? "Wired Claude MCP: .mcp.json (agentboard stdio)" : "Claude MCP already wired: .mcp.json");
+      return ["approve .mcp.json when Claude prompts (project MCP servers need approval)", "set AGENTBOARD_AGENT=<you> once per terminal for the hooks"];
+    }
+    case "codex": {
+      const changedHooks = mergeHookGroups(path.join(cwd, ".codex", "hooks.json"), hookAbs, boardExtra, {
+        SessionStart: "session-start",
+        Stop: "codex",
+      });
+      console.log(changedHooks ? "Wired Codex hooks: .codex/hooks.json (SessionStart + Stop)" : "Codex hooks already wired: .codex/hooks.json");
+      return [
+        `run: ${mcpRunCmd(ctx, mcpAbs, "codex")}  (for dm_send/dm_inbox tools)`,
+        "open /hooks and trust the project hooks before they run",
+        "set AGENTBOARD_AGENT=<you> once per terminal for the hooks",
+      ];
+    }
+    case "antigravity": {
+      const changedHooks = mergeAntigravityHooks(path.join(cwd, ".agents", "hooks.json"), hookAbs, boardExtra);
+      console.log(changedHooks ? "Wired Antigravity hooks: .agents/hooks.json (Stop + PreInvocation)" : "Antigravity hooks already wired: .agents/hooks.json");
+      const entry = mcpEntry(ctx, mcpAbs);
+      const changedMcp = mergeMcpServers(path.join(cwd, ".agents", "mcp_config.json"), entry);
+      console.log(changedMcp ? "Wired Antigravity MCP: .agents/mcp_config.json (agentboard stdio)" : "Antigravity MCP already wired: .agents/mcp_config.json");
+      return ["set AGENTBOARD_AGENT=<you> once per terminal for the hooks"];
+    }
+    case "grok": {
+      const changedHooks = mergeHookGroups(path.join(cwd, ".grok", "hooks", "agentboard.json"), hookAbs, boardExtra, {
+        SessionStart: "session-start",
+        Stop: "grok",
+      });
+      console.log(changedHooks ? "Wired grok hooks: .grok/hooks/agentboard.json (SessionStart + Stop)" : "grok hooks already wired: .grok/hooks/agentboard.json");
+      return [
+        `run: ${mcpRunCmd(ctx, mcpAbs, "grok")}  (for DM tools)`,
+        "grant folder trust (/hooks-trust or --trust) so project hooks + AGENTS.md load",
+        "set AGENTBOARD_AGENT=<you> once per terminal for the hooks",
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+function cmdInit(args) {
+  const root = boardDir(args);
+  ensureBoard(root);
+  const force = args.includes("--force");
+  const noOpencode = args.includes("--no-opencode");
+  if (root === path.join(process.cwd(), ".agentboard")) {
+    if (fs.existsSync(path.join(process.cwd(), ".git"))) {
+      const gitIgnore = path.join(process.cwd(), ".gitignore");
+      let gi = "";
+      try {
+        gi = fs.readFileSync(gitIgnore, "utf8");
+      } catch {}
+      if (!/^\.agentboard\/?\s*$/m.test(gi)) {
+        const addition = (gi && !gi.endsWith("\n") ? "\n" : "") + "# agent-board state\n.agentboard/\n";
+        fs.appendFileSync(gitIgnore, addition);
+        console.log("Added .agentboard/ to .gitignore");
+      }
+    }
+    const snippet = AGENTS_MD_SNIPPET.replaceAll("{CLI}", cliInvoke());
+    upsertAgentsMd(process.cwd(), snippet);
+    // harness wiring: explicit --harness wins, else union of detected markers,
+    // else legacy default (opencode) so old checkouts keep working.
+    let ids = parseHarnessFlag(args);
+    if (ids.length === 0) {
+      ids = detectHarnesses(process.cwd());
+      if (ids.length === 0) {
+        ids = ["opencode"];
+        console.log("No harness markers detected (.opencode/.claude/.codex/.agents/.grok) — defaulting to opencode (use --harness to choose)");
+      } else {
+        console.log(`Detected harness markers: ${ids.join(", ")} (use --harness to override)`);
+      }
+    }
+    if (noOpencode) ids = ids.filter((h) => h !== "opencode");
+    if (ids.includes("generic") && ids.length > 1) ids = ids.filter((h) => h !== "generic");
+  const nonLocal = root !== path.join(process.cwd(), ".agentboard");
+  const boardExtra = nonLocal ? `--board "${root.split(path.sep).join("/")}"` : "";
+  const mcpEnv = nonLocal ? { AGENTBOARD_DIR: root } : null;
+  const portable = args.includes("--portable");
+  if (portable) console.log("Portable mode: MCP entries use the agentboard-mcp binary (needs npm i -g . first)");
+  const ctx = { force, hookAbs: binAbs("agentboard-hook.js"), mcpAbs: binAbs("agentboard-mcp.js"), boardExtra, mcpEnv, portable };
+    const followUps = [];
+    for (const h of ids) {
+      if (h === "generic") continue;
+      for (const f of applyHarness(process.cwd(), h, ctx)) {
+        if (!followUps.includes(f)) followUps.push(f);
+      }
+    }
+    if (!nonLocal) upsertHarnessSections(process.cwd(), cliInvoke(), ids);
+    recordHarnesses(root, ids);
+    for (const f of followUps) console.log(`Follow-up: ${f}`);
+  } else {
+    console.log(`(non-local board: skipping AGENTS.md/harness install for ${root})`);
+  }
+  console.log(`Board ready at ${root}`);
+  console.log(`Point other agents here with:  set AGENTBOARD_DIR=${root}`);
+  console.log(`Tip: set AGENTBOARD_AGENT=<your-name> to skip --from on every command`);
+}
+
+function touchAgent(d, name, extra) {
+  const p = path.join(d.agents, `${name}.json`);
+  const now = new Date().toISOString();
+  let prev = null;
+  try {
+    prev = readJson(p);
+  } catch {}
+  const doc = {
+    name,
+    firstSeen: (prev && prev.firstSeen) || now,
+    lastSeen: now,
+    sessionId: (extra && extra.sessionId) || (prev && prev.sessionId) || undefined,
+    lastDir: (extra && extra.lastDir) || (prev && prev.lastDir) || undefined,
+  };
+  writeJson(p, doc);
+  return doc;
+}
+
+function cmdRegister(args) {
+  const d = ensureBoard(boardDir(args));
+  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})` : ""}`);
+}
+
+function cmdAgents(args) {
+  const d = ensureBoard(boardDir(args));
+  const items = listJson(d.agents)
+    .map((e) => e.data)
+    .filter((x) => x && x.name)
+    .sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(items, null, 2));
+    return;
+  }
+  if (items.length === 0) {
+    console.log("no agents registered (register --from <you>)");
+    return;
+  }
+  for (const a of items) {
+    console.log(`${a.name}  (last seen ${relTime(a.lastSeen)}${a.sessionId ? `, session ${a.sessionId}` : ""})`);
+  }
+}
+
+function cmdSend(args) {
+  const d = ensureBoard(boardDir(args));
+  const from = resolveAgent(args, "sender");
+  const toRaw = getFlag(args, "--to");
+  const to = sanitizeName(toRaw, "recipient");
+  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 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}`);
+}
+
+function readDMs(d, recipient) {
+  return listJson(path.join(d.dm, recipient))
+    .map((e) => e.data)
+    .filter((x) => x && x.id && x.from)
+    .sort((a, b) => (String(a.at).localeCompare(String(b.at)) || String(a.id).localeCompare(String(b.id))));
+}
+
+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(`  ${m.body}`);
+  console.log("");
+}
+
+function cmdInbox(args) {
+  const d = ensureBoard(boardDir(args));
+  const showAll = args.includes("--all");
+  const limit = Number(getFlag(args, "--limit") || 20);
+  const after = getFlag(args, "--after");
+  const json = args.includes("--json");
+  let items;
+  let showTo = false;
+  if (showAll) {
+    items = [];
+    let subs = [];
+    try {
+      subs = fs.readdirSync(d.dm);
+    } catch {
+      subs = [];
+    }
+    for (const sub of subs) {
+      let st = null;
+      try {
+        st = fs.statSync(path.join(d.dm, sub));
+      } catch {
+        continue;
+      }
+      if (!st.isDirectory()) continue;
+      for (const m of readDMs(d, sub)) items.push(m);
+    }
+    items.sort((a, b) => String(a.at).localeCompare(String(b.at)) || String(a.id).localeCompare(String(b.id)));
+    showTo = true;
+  } else {
+    const agent = resolveAgent(args, "reader");
+    items = readDMs(d, agent);
+  }
+  if (after) {
+    const idx = items.findIndex((m) => m.id === after);
+    if (idx !== -1) items = items.slice(idx + 1);
+  }
+  items = items.slice(-Math.max(limit, 0));
+  if (json) {
+    console.log(JSON.stringify(items, null, 2));
+    return;
+  }
+  if (items.length === 0) {
+    console.log(showAll ? "no messages" : `no messages for ${resolveAgent(args, "reader")}`);
+    return;
+  }
+  for (const m of items) printMsg(m, showTo, false);
+}
+
+async function cmdListen(args) {
+  const d = ensureBoard(boardDir(args));
+  const agent = resolveAgent(args, "listener");
+  const timeoutMs = Number(getFlag(args, "--timeout") || 0);
+  const json = args.includes("--json");
+  if (!(timeoutMs >= 0)) fail("--timeout must be a non-negative number of ms");
+  const dir = path.join(d.dm, agent);
+  fs.mkdirSync(dir, { recursive: true });
+  const seen = new Set(readDMs(d, agent).map((m) => m.id));
+  // print backlog first so a fresh listener doesn't miss history
+  for (const m of readDMs(d, agent)) printMsg(m, false, json);
+  let done = false;
+  let timer = null;
+  const finish = () => {
+    if (!done) {
+      done = true;
+      if (timer) clearTimeout(timer);
+    }
+  };
+  process.on("SIGINT", () => {
+    finish();
+    process.exit(0);
+  });
+  const scan = () => {
+    for (const m of readDMs(d, agent)) {
+      if (!seen.has(m.id)) {
+        seen.add(m.id);
+        printMsg(m, false, json);
+      }
+    }
+  };
+  let watcher = null;
+  try {
+    watcher = fs.watch(dir, () => scan());
+  } catch {}
+  const poll = setInterval(() => {
+    if (done) {
+      clearInterval(poll);
+      return;
+    }
+    scan();
+  }, 500);
+  if (timeoutMs > 0) {
+    await new Promise((res) => {
+      timer = setTimeout(res, timeoutMs);
+    });
+  } else {
+    await new Promise(() => {});
+  }
+  clearInterval(poll);
+  try {
+    if (watcher) watcher.close();
+  } catch {}
+  finish();
+}
+
+// ---------------------------------------------------------------------------
+// doctor: validate board + harness wiring
+// ---------------------------------------------------------------------------
+
+function cmdDoctor(args) {
+  const root = boardDir(args);
+  const cwd = process.cwd();
+  const local = root === path.join(cwd, ".agentboard");
+  let bad = 0;
+  const ok = (label) => console.log(`ok    ${label}`);
+  const no = (label, hint) => {
+    bad++;
+    console.log(`FAIL  ${label}${hint ? ` — ${hint}` : ""}`);
+  };
+  const info = (label) => console.log(`info  ${label}`);
+
+  const nodeMajor = Number(String(process.version).replace(/^v/, "").split(".")[0]);
+  if (nodeMajor >= 18) ok(`node ${process.version} (>= 18)`);
+  else no(`node ${process.version} (>= 18 required)`);
+
+  const meta = readJsonFile(path.join(root, "board.json"), null);
+  if (meta && meta.version === 2) ok(`board at ${root} (v2)`);
+  else no(`board at ${root}`, "run: agentboard init");
+
+  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));
+    else {
+      ids = detectHarnesses(cwd);
+      if (ids.length === 0) ids = ["generic"];
+    }
+  }
+  if (!local) {
+    info(`non-local board: skipping project-file checks for ${root}`);
+    console.log(bad === 0 ? "doctor: healthy" : `doctor: ${bad} problem(s)`);
+    if (bad > 0) process.exitCode = 1;
+    return;
+  }
+
+  const md = (() => {
+    try {
+      return fs.readFileSync(path.join(cwd, "AGENTS.md"), "utf8");
+    } catch {
+      return "";
+    }
+  })();
+  if (md.includes("agentboard:start")) ok("AGENTS.md core block");
+  else no("AGENTS.md core block", "run: agentboard init");
+
+  const hasHookRef = (file, events) => {
+    const obj = readJsonFile(file, null);
+    if (!obj || typeof obj.hooks !== "object") return false;
+    return events.every(
+      (ev) =>
+        Array.isArray(obj.hooks[ev]) &&
+        obj.hooks[ev].some((g) => g && g.hooks && g.hooks.some((h) => String((h && h.command) || "").includes("agentboard-hook")))
+    );
+  };
+  const hasMcpServer = (file) => {
+    const obj = readJsonFile(file, null);
+    return !!(obj && obj.mcpServers && obj.mcpServers.agentboard && obj.mcpServers.agentboard.command);
+  };
+
+  for (const h of ids) {
+    switch (h) {
+      case "opencode":
+        if (fs.existsSync(path.join(cwd, ".opencode", "tools", "dm-send.js"))) ok("opencode tool .opencode/tools/dm-send.js");
+        else no("opencode tool .opencode/tools/dm-send.js", "run: agentboard init --harness opencode (then restart opencode)");
+        if (fs.existsSync(path.join(cwd, ".opencode", "plugins", "dm-watch.js"))) ok("opencode plugin .opencode/plugins/dm-watch.js");
+        else no("opencode plugin .opencode/plugins/dm-watch.js", "run: agentboard init --harness opencode (then restart opencode)");
+        break;
+      case "claude":
+        if (hasHookRef(path.join(cwd, ".claude", "settings.json"), ["SessionStart", "Stop"])) ok("claude hooks .claude/settings.json");
+        else no("claude hooks .claude/settings.json", "run: agentboard init --harness claude");
+        if (hasMcpServer(path.join(cwd, ".mcp.json"))) ok("claude MCP .mcp.json");
+        else no("claude MCP .mcp.json", "run: agentboard init --harness claude (then approve it in Claude)");
+        break;
+      case "codex":
+        if (hasHookRef(path.join(cwd, ".codex", "hooks.json"), ["SessionStart", "Stop"])) ok("codex hooks .codex/hooks.json");
+        else no("codex hooks .codex/hooks.json", "run: agentboard init --harness codex (then trust them in /hooks)");
+        info("codex MCP is a CLI step: codex mcp add agentboard -- node <board-checkout>/bin/agentboard-mcp.js");
+        break;
+      case "antigravity": {
+        const obj = readJsonFile(path.join(cwd, ".agents", "hooks.json"), null);
+        if (obj && obj["agentboard-dm"] && obj["agentboard-dm"].Stop) ok("antigravity hooks .agents/hooks.json");
+        else no("antigravity hooks .agents/hooks.json", "run: agentboard init --harness antigravity");
+        if (hasMcpServer(path.join(cwd, ".agents", "mcp_config.json"))) ok("antigravity MCP .agents/mcp_config.json");
+        else no("antigravity MCP .agents/mcp_config.json", "run: agentboard init --harness antigravity");
+        break;
+      }
+      case "grok":
+        if (hasHookRef(path.join(cwd, ".grok", "hooks", "agentboard.json"), ["SessionStart", "Stop"])) ok("grok hooks .grok/hooks/agentboard.json");
+        else no("grok hooks .grok/hooks/agentboard.json", "run: agentboard init --harness grok (then /hooks-trust)");
+        info("grok MCP is a CLI step: grok mcp add --scope project agentboard -- node <board-checkout>/bin/agentboard-mcp.js");
+        break;
+      default:
+        info(`generic harness: CLI pull only (inbox/listen), nothing to validate`);
+        break;
+    }
+  }
+  if (!process.env.AGENTBOARD_AGENT) info("AGENTBOARD_AGENT is unset — hooks need it to know who you are");
+  console.log(bad === 0 ? "doctor: healthy" : `doctor: ${bad} problem(s)`);
+  if (bad > 0) process.exitCode = 1;
+}
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+
+const REMOVED = new Set([
+  "task", "tasks", "show", "claim", "progress", "verify", "done", "abandon",
+  "reap", "edit", "assign", "split", "hold", "release", "veto", "digest",
+  "say", "messages", "sweep", "watch", "stats",
+]);
+
+const USAGE = `agentboard — DM-only minimal bus for AI agent coordination (v2)
+
+Setup:
+  agentboard init [--global] [--board <path>] [--force] [--no-opencode] [--portable]
+                 [--harness opencode,claude,codex,antigravity,grok,generic]
+    create board in ./.agentboard, write AGENTS.md block, install harness
+    wiring (hooks + MCP config + notes). Without --harness, init applies the
+    union of detected markers (.opencode/.claude/.codex/.agents/.grok).
+
+Identity:
+  agentboard register --from <you> [--session <opencode-session-id>]
+  agentboard agents [--json]
+
+Messaging (primitive — just a tool call, whenever you want):
+  agentboard send --from <you> --to <peer> --body "..." [--session <id>]
+  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 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`;
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+  if (REMOVED.has(cmd)) {
+    fail(`"${cmd}" was removed in v2 DM-only — use "send --from A --to B --body ..." (+ inbox/listen). See --help.`);
+  }
+  switch (cmd) {
+    case "init": return cmdInit(rest);
+    case "register": return cmdRegister(rest);
+    case "agents": return cmdAgents(rest);
+    case "send": return cmdSend(rest);
+    case "inbox": return cmdInbox(rest);
+    case "listen": return await cmdListen(rest);
+    case "doctor": return cmdDoctor(rest);
+    case undefined:
+    case "-h":
+    case "--help":
+    case "help":
+      console.log(USAGE);
+      return;
+    default:
+      fail(`unknown command "${cmd}"\n\n${USAGE}`);
+  }
+}
+
+main().catch((e) => {
+  fail(e && e.stack ? e.stack : String(e));
+});