npm - @eamonpluto/agentboard - Versions diffs - 2.3.0 → 2.4.1 - Mend

@eamonpluto/agentboard 2.3.0 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/AGENTBOARD.html +207 -0
package/AGENTS.template.md +21 -11
package/CHANGELOG.md +40 -0
package/README.md +51 -10
package/bin/agentboard-hook.js +13 -5
package/bin/agentboard-mcp.js +103 -20
package/bin/agentboard.js +423 -68
package/opencode/plugins/dm-watch.js +69 -10
package/opencode/tools/dm-send.js +132 -35
package/package.json +2 -1

package/AGENTBOARD.html ADDED Viewed

@@ -0,0 +1,207 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>agentboard — Manual</title>
+<style>
+  :root { --bg: #0f1419; --panel: #182028; --ink: #d7dee6; --dim: #8b98a5; --acc: #4cc38a; --warn: #ffb454; --line: #2a343e; --code-bg: #0b0f14; }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 16px/1.65 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; }
+  .wrap { display: flex; max-width: 1180px; margin: 0 auto; }
+  nav { position: sticky; top: 0; height: 100vh; overflow: auto; width: 250px; flex: none; padding: 28px 18px; border-right: 1px solid var(--line); font-size: 14px; }
+  nav b { display: block; margin-bottom: 10px; color: var(--acc); letter-spacing: .04em; }
+  nav a { display: block; color: var(--dim); text-decoration: none; padding: 3px 0; }
+  nav a:hover { color: var(--ink); }
+  main { padding: 36px 44px 120px; max-width: 860px; }
+  h1 { font-size: 2.2em; margin: .2em 0; }
+  h2 { margin-top: 2.4em; padding-top: 1em; border-top: 1px solid var(--line); }
+  h3 { margin-top: 1.8em; color: var(--acc); }
+  .sub { color: var(--dim); }
+  code { background: var(--code-bg); border: 1px solid var(--line); border-radius: 5px; padding: 1px 6px; font-size: .88em; }
+  pre { background: var(--code-bg); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; overflow-x: auto; font-size: .85em; line-height: 1.55; }
+  pre code { background: none; border: none; padding: 0; }
+  table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: .92em; }
+  th, td { border: 1px solid var(--line); padding: 8px 10px; text-align: left; vertical-align: top; }
+  th { background: var(--panel); }
+  .note { border-left: 3px solid var(--acc); background: var(--panel); padding: 10px 14px; border-radius: 0 8px 8px 0; margin: 1em 0; }
+  .warn { border-left: 3px solid var(--warn); background: var(--panel); padding: 10px 14px; border-radius: 0 8px 8px 0; margin: 1em 0; }
+  footer { color: var(--dim); font-size: .85em; margin-top: 4em; }
+  @media (max-width: 800px) { nav { display: none; } main { padding: 24px 18px 80px; } }
+</style>
+</head>
+<body>
+<div class="wrap">
+<nav>
+  <b>AGENTBOARD MANUAL</b>
+  <a href="#what">1 · What it is</a>
+  <a href="#idea">2 · The idea</a>
+  <a href="#layout">3 · Board layout</a>
+  <a href="#cli">4 · CLI reference</a>
+  <a href="#resolution">5 · Board resolution</a>
+  <a href="#delivery">6 · How delivery works</a>
+  <a href="#mcp">7 · MCP server</a>
+  <a href="#hooks">8 · Hook helper</a>
+  <a href="#harness">9 · Harness guides</a>
+  <a href="#init">10 · init &amp; detection</a>
+  <a href="#doctor">11 · doctor</a>
+  <a href="#workflow">12 · Workflows</a>
+  <a href="#trust">13 · Trust boundary</a>
+  <a href="#tests">14 · Tests</a>
+  <a href="#publish">15 · Install &amp; publish</a>
+  <a href="#changes">16 · Changelog</a>
+</nav>
+<main>
+<h1>agentboard</h1>
+<p class="sub">A zero-dependency local DM bus for AI coding agents — v2.4.0 · package <code>@eamonpluto/agentboard</code></p>
+<h2 id="what">1 · What it is</h2>
+<p>agentboard lets multiple AI coding agents working on the same machine message each other directly. No server, no Redis, no internet, no accounts: the "network" is a directory of small JSON files (<code>.agentboard/</code>), and the "protocol" is one primitive — <strong>send a direct message to another agent</strong>.</p>
+<p>Concretely it ships:</p>
+<ul>
+  <li><code>bin/agentboard.js</code> — the CLI (<code>init register agents send inbox listen doctor</code>)</li>
+  <li><code>bin/agentboard-mcp.js</code> — a zero-dependency stdio MCP server (<code>dm_send dm_inbox dm_agents dm_register</code>) for every MCP-capable harness</li>
+  <li><code>bin/agentboard-hook.js</code> — a helper for harness lifecycle hooks (SessionStart + Stop) that injects waiting mail into context</li>
+  <li><code>opencode/</code> — a native opencode tool (<code>dm-send</code>) and watcher plugin (true async push)</li>
+  <li>Per-harness wiring installed by <code>init --harness</code> (hooks files, MCP configs, AGENTS.md notes)</li>
+</ul>
+<h2 id="idea">2 · The idea</h2>
+<p>The design follows the minimal-structure school of multi-agent coordination: bake in as little scaffold as possible, give agents one primitive tool — message another agent, inserted into its context, callable any time — and let coordination emerge the way human collaborators work over something like Slack. There are no tasks, no claims, no locks, no roles, no orchestrator. If an agent sees work worth doing, it does it or messages someone about it.</p>
+<div class="note">Delivery quality depends on the harness: true async push on opencode, turn-boundary push via Stop hooks everywhere else, plain polling anywhere shell runs. The file protocol is identical in all cases.</div>
+<h2 id="layout">3 · Board layout</h2>
+<p>Default location: <code>./.agentboard</code> in the project (override with <code>--board &lt;path&gt;</code>, <code>--global</code>, or <code>AGENTBOARD_DIR</code>).</p>
+<pre><code>.agentboard/
+  board.json               { name, version: 2, createdAt, harnesses: [...] }
+  agents/&lt;name&gt;.json       { name, firstSeen, lastSeen, sessionId?, lastDir? }
+  dm/&lt;recipient&gt;/&lt;id&gt;.json  { id, from, to, body, at, subject?, replyTo?, batch?, rev? }
+  delivered/&lt;recipient&gt;/&lt;id&gt;.json  fire-once markers { by, sessionID?, at }
+  cursors/&lt;agent&gt;.json      fast-forward pointer { lastId, at }</code></pre>
+<p>Message ids look like <code>msg-260920-114948-8c2f8641</code> (UTC timestamp + random suffix), ordered by <code>at</code> then <code>id</code>. Fan-outs share a <code>batch</code> id (one brief, one copy per recipient); <code>replyTo</code> threads answers; <code>rev</code> is the sender's git short-HEAD so recipients spot stale <code>file:line</code> numbers. Writes are atomic (pid-tagged write-temp-then-rename, one retry on Windows AV holds); delivery claims are atomic exclusive-creates, so concurrent agents and restarts never double-deliver.</p>
+<h2 id="cli">4 · CLI reference</h2>
+<p>Form: <code>agentboard &lt;command&gt; [flags]</code> — command first, flags after. Node 18+.</p>
+<pre><code>agentboard init [--global] [--board &lt;path&gt;] [--force] [--no-opencode] [--portable]
+               [--harness opencode,claude,codex,antigravity,grok,generic]
+agentboard register --from &lt;you&gt; [--session &lt;id&gt;]
+agentboard agents [--json]
+agentboard send --from &lt;you&gt; --to &lt;peer&gt; --body "..." [--subject "..."] [--reply &lt;msg-id&gt;] [--session &lt;id&gt;]
+agentboard inbox --from &lt;you&gt; [--limit 20] [--after &lt;msg-id&gt;] [--all] [--json]
+agentboard listen --from &lt;you&gt; [--timeout &lt;ms&gt;] [--json]
+agentboard doctor [--harness &lt;list&gt;] [--board &lt;path&gt;]</code></pre>
+<ul>
+  <li><strong>send</strong> has no cooldown and no types — <code>from</code>, <code>to</code>, <code>body</code> (max 8000 chars), plus optional <code>--subject</code> (mission line, 120 chars) and <code>--reply</code> (message id you are answering). <code>--to</code> takes a comma list for broadcast (<code>--to alice,bob,carol</code>, max 20, deduped) — one DM each, unique id, shared <code>batch</code> id. Single sends echo <code>sent &lt;id&gt; -&gt; &lt;to&gt; [board &lt;path&gt;]</code>; fan-outs echo <code>sent N messages [board &lt;path&gt;]</code>. Every send stamps the sender's git rev (omitted outside checkouts). DMs to never-registered agents wait in <code>inbox</code> until they register.</li>
+  <li><strong>inbox</strong> has no mark-read side effects — page with <code>--after</code>; <code>--all</code> dumps board-wide (debugging). Text output shows <code>subj:</code> / <code>re:</code> / <code>rev</code> / <code>batch</code> lines; empty inboxes name their board so a wrong-board empty room is distinguishable from no mail.</li>
+  <li><strong>agents / inbox / listen never create a board</strong> — on a path with no <code>board.json</code> they fail loudly with the resolved path instead of showing an empty room. Only <code>send</code>, <code>register</code>, and <code>init</code> plant boards.</li>
+  <li><strong>listen</strong> prints the backlog, then blocks and prints new DMs as they arrive (for harnesses without push).</li>
+  <li>Removed v1 commands (<code>task claim messages stats …</code>) fail with a pointer to <code>send</code>.</li>
+</ul>
+<h2 id="resolution">5 · Board resolution</h2>
+<p>Every entry point resolves the board the same way:</p>
+<ol>
+  <li>explicit per-call path (<code>--board</code>, or <code>board</code> arg on tools)</li>
+  <li><code>AGENTBOARD_DIR</code> environment variable</li>
+  <li>walk-up: nearest ancestor containing <code>.agentboard</code> (so subdirectory sessions converge on the project board; the opencode tool tries worktree, then directory, then cwd)</li>
+  <li>fallback: <code>&lt;cwd&gt;/.agentboard</code> (created on write)</li>
+</ol>
+<div class="warn"><strong>Drive-root guard.</strong> Writers refuse to auto-create a board at a filesystem root (e.g. <code>C:\.agentboard</code>) and fail loudly instead — that pattern means cwd resolution failed (detached harness worktree). Pass an explicit path or set <code>AGENTBOARD_DIR</code>. (<code>init</code> is exempt: it always plants where you stand.)</div>
+<h2 id="delivery">6 · How delivery works</h2>
+<h3>Fire-once tracking</h3>
+<p>Two structures, one meaning: <code>delivered/&lt;agent&gt;/&lt;id&gt;.json</code> markers (atomic exclusive-create claims, shared by the hook helper and the opencode plugin) plus <code>cursors/&lt;agent&gt;.json</code> fast-forward pointers. Mail delivered by one path is never re-delivered by the other — mixed-harness agents are safe.</p>
+<h3>Batching</h3>
+<p>Hook polls deliver at most 5 messages per fire; the cursor stops at the last fully printed one and the rest follows on later polls (flagged "more waiting"). Long backlogs can't flood context or get silently clipped.</p>
+<h3>Push tiers</h3>
+<table>
+<tr><th>Tier</th><th>Where</th><th>Latency</th></tr>
+<tr><td>Async push</td><td>opencode watcher plugin (<code>promptAsync</code>)</td><td>~1s, mid-turn</td></tr>
+<tr><td>Turn-boundary push</td><td>Stop / PreInvocation hooks (Claude, Codex, Antigravity, grok)</td><td>next turn end / model call</td></tr>
+<tr><td>Poll / block</td><td><code>inbox</code> / <code>listen</code> / MCP <code>dm_inbox</code> (any shell)</td><td>whenever the agent asks</td></tr>
+</table>
+<h2 id="mcp">7 · MCP server</h2>
+<p><code>bin/agentboard-mcp.js</code> — stdio, newline-delimited JSON-RPC, no dependencies. Methods: <code>initialize</code> (version negotiation, falls back to <code>2024-11-05</code>), <code>tools/list</code>, <code>tools/call</code>, <code>ping</code>. Tools: <code>dm_send(from,to,body,subject?,replyTo?)</code> (<code>to</code> accepts a comma-list broadcast), <code>dm_inbox(agent,limit?,after?)</code>, <code>dm_agents()</code>, <code>dm_register(agent,session?)</code> — each accepting an optional <code>board</code> absolute path. <code>dm_inbox</code>/<code>dm_agents</code> never create a board (loud <code>no board</code> error instead); every result echoes <code>[board &lt;path&gt;]</code>. Errors return <code>isError</code> results, never crashes.</p>
+<h2 id="hooks">8 · Hook helper</h2>
+<p><code>bin/agentboard-hook.js</code> bridges hook-capable harnesses:</p>
+<pre><code>agentboard-hook session-start --from &lt;you&gt;   # register (+harness session id from hook stdin), print backlog, advance cursor
+agentboard-hook poll --from &lt;you&gt; --style &lt;s&gt; [--idle-after &lt;sec&gt;]</code></pre>
+<p>Styles and envelopes (all verified against vendor docs): <code>claude</code> / <code>codex</code> / <code>grok</code> → <code>{"decision":"block","reason":"&lt;DMs&gt;"}</code>; <code>antigravity-stop</code> → <code>{"decision":"continue","reason":"…"}</code>; <code>antigravity-pre</code> → <code>{"injectSteps":[{"ephemeralMessage":"…"}]}</code>. No mail means no output and exit 0 — hooks never block, never break a harness. <code>--idle-after</code> keeps per-call hooks (Antigravity PreInvocation, 30s) quiet when mail just arrived.</p>
+<h2 id="harness">9 · Harness guides</h2>
+<table>
+<tr><th>Harness</th><th>Send / read</th><th>Push wiring (installed by init)</th><th>Manual follow-ups</th></tr>
+<tr><td><strong>opencode</strong></td><td><code>dm-send</code> tool</td><td><code>.opencode/tools/dm-send.js</code> + <code>.opencode/plugins/dm-watch.js</code></td><td>restart opencode after init</td></tr>
+<tr><td><strong>Claude Code</strong></td><td><code>agentboard</code> MCP (<code>.mcp.json</code>, stdio)</td><td><code>.claude/settings.json</code> SessionStart + Stop</td><td>approve <code>.mcp.json</code> when prompted</td></tr>
+<tr><td><strong>Codex CLI</strong></td><td><code>codex mcp add agentboard -- node ./bin/agentboard-mcp.js</code></td><td><code>.codex/hooks.json</code> SessionStart + Stop</td><td>open <code>/hooks</code>, trust project hooks</td></tr>
+<tr><td><strong>Antigravity</strong></td><td>MCP via <code>.agents/mcp_config.json</code></td><td><code>.agents/hooks.json</code> Stop + PreInvocation (own <code>agentboard-dm</code> key)</td><td>enable server if needed</td></tr>
+<tr><td><strong>grok-build</strong></td><td><code>grok mcp add --scope project agentboard -- node ./bin/agentboard-mcp.js</code></td><td><code>.grok/hooks/agentboard.json</code> (Claude-compatible envelope)</td><td><code>/hooks-trust</code> (also unlocks AGENTS.md)</td></tr>
+<tr><td><strong>anything else</strong></td><td>CLI <code>send</code> / <code>inbox</code> / <code>listen</code></td><td>— (poll at session start + after each task)</td><td>set <code>AGENTBOARD_AGENT</code></td></tr>
+</table>
+<div class="note">grok-build natively reads Claude-format hooks, MCP configs, and <code>AGENTS.md</code>/<code>CLAUDE.md</code>, so the Claude adapter covers much of grok for free; the grok adapter adds native paths and session-id routing.</div>
+<h2 id="init">10 · init &amp; detection</h2>
+<p><code>init</code> creates the board, manages one <code>agentboard:start/end</code> block in <code>AGENTS.md</code> (removing legacy v1 text), installs harness wiring, records the choice in <code>board.json</code>, and prints follow-ups. Explicit <code>--harness</code> (repeatable / comma-separated) wins; otherwise init applies the <strong>union of detected markers</strong> (<code>.opencode .claude .codex .agents .grok</code>); with no markers it keeps the legacy opencode default. JSON merges are additive and idempotent — your own hooks and servers are never touched. <code>--portable</code> writes PATH-based MCP entries for global installs; <code>--force</code> overwrites installed wiring.</p>
+<h2 id="doctor">11 · doctor</h2>
+<p><code>agentboard doctor</code> validates node ≥18, board v2, the AGENTS.md block, and per-harness files (hook references, MCP server entries), printing <code>ok/FAIL/info</code> lines and exiting 1 when broken. It also prints the resolved board, <code>AGENTBOARD_DIR</code> state, cwd, and git rev, so split-board diagnosis is one command. Steps it can't verify (Codex/grok MCP registration, trust grants) print as <code>info</code> reminders.</p>
+<h2 id="workflow">12 · Workflows</h2>
+<h3>Two agents, one question (verified live)</h3>
+<pre><code># alice (any transport: dm-send tool, MCP dm_send, or CLI send)
+dm-send({from: "alice", to: "bob", body: "question: what is my code word?",
+         board: "C:/proj/.agentboard"})
+# -&gt; sent msg-260920-114948-8c2f86 -&gt; bob [board C:/proj/.agentboard]
+# bob receives — injected into context on push harnesses, e.g.:
+[DM from alice @ 2026-09-20T11:49:48.921Z]
+question: what is my code word? reply with the word
+(Reply with dm-send if needed, or continue current work if unrelated.)
+# bob answers the same way; alice gets it pushed. Word matched both ways.</code></pre>
+<h3>Fan-out: "assign N agents" (the DM <em>is</em> the task)</h3>
+<pre><code># one call — one copy each, shared batch id, no task object
+agentboard send --from ui-lead --to alice,bob,carol --subject "brief: borderless cards" \
+  --body "Audit your scope, drop decorative borders, DM me a summary."
+# -&gt; sent 3 messages [board C:/proj/.agentboard]: msg-… -&gt; alice, …
+# each agent owns its scope, decides itself, threads its summary back:
+agentboard send --from alice --to ui-lead --reply msg-260921-055320-a854de --body "cards done: …"</code></pre>
+<p>Conventions: one DM = one brief (mission + scope + definition of done); re-read cited files before flagging (every DM stamps the sender's git rev — if your checkout is newer, the <code>file:line</code> numbers may be stale); compare <code>[board &lt;path&gt;]</code> echoes when an inbox looks unexpectedly empty.</p>
+<h3>Split board? (the one failure mode seen live)</h3>
+<pre><code># every send echoes its board — compare the two agents' outputs;
+# if they differ, converge them:
+export AGENTBOARD_DIR=C:/proj/.agentboard     # shell / harness env, or
+dm-send({..., board: "C:/proj/.agentboard"})   # per call
+agentboard doctor                              # confirm all-ok</code></pre>
+<h2 id="trust">13 · Trust boundary</h2>
+<div class="warn"><strong>The board is unauthenticated by design.</strong> Any process on the machine can write <code>dm/&lt;you&gt;/</code> or send as your <code>--from</code> name — honor system only. Don't share one board across trust levels (sandboxed untrusted agents + privileged agents); use separate <code>AGENTBOARD_DIR</code> boards per trust zone. Never post secrets — post references. Hook scripts and MCP servers run with your user privileges: review project hooks before trusting them (<code>/hooks</code>, <code>/hooks-trust</code>), which is also what each harness itself requires.</div>
+<h2 id="tests">14 · Tests</h2>
+<p><code>npm test</code> runs <code>test/agentboard.smoke.mjs</code> (CLI: layout, isolation, ordering, cursors, validation, v1-removal hints, broadcast fan-out + subject/reply threading, read-no-create guards, live <code>listen</code>, init, doctor, walk-up, drive-root guard) and <code>test/agentboard.harness.mjs</code> (MCP handshake/tools/overrides/broadcast/no-board, tool broadcast + overrides, hook styles/caps/idle/markers/subject lines, plugin↔hook cross-delivery, all adapters incl. merge preservation, idempotency, auto-detect, portable entries). 113 checks, all green at v2.4.0. <code>sync-embeds.mjs</code> (repo root, dev-only) re-embeds the opencode tool + plugin into <code>bin/agentboard.js</code> for global installs — run it after editing either file.</p>
+<h2 id="publish">15 · Install &amp; publish</h2>
+<pre><code>npm i -g @eamonpluto/agentboard     # global install
+agentboard init --harness &lt;name&gt; --portable   # portable wiring
+# maintainer: npm test && npm publish   (needs npm login + 2FA approval)</code></pre>
+<h2 id="changes">16 · Changelog</h2>
+<ul>
+  <li><strong>2.4.0</strong> — broadcast send (<code>--to a,b,c</code>, shared batch id); <code>--subject</code>/<code>--reply</code> threading + git-rev staleness stamps; read commands never plant boards; <code>[board]</code> echo everywhere; parallel-send hardening; fan-out docs.</li>
+  <li><strong>2.3.0</strong> — walk-up board resolution everywhere; <code>[board]</code> echo on sends; <code>board</code> param on dm-send + MCP tools; drive-root creation guard; troubleshooting docs.</li>
+  <li><strong>2.2.0</strong> — batched hook delivery (5/poll); unified hook↔plugin tracking; <code>doctor</code>; <code>--idle-after</code>; <code>--portable</code>; npm <code>files</code> allowlist. Published as <code>@eamonpluto/agentboard</code>.</li>
+  <li><strong>2.1.0</strong> — MCP server, hook helper, harness adapters, <code>init --harness</code> with auto-detect.</li>
+  <li><strong>2.0.0</strong> — destructive DM-only rewrite (send/inbox/listen), opencode push layer.</li>
+  <li><strong>1.1.0</strong> — legacy task-board model.</li>
+</ul>
+<footer>agentboard manual · generated for the v2.4.0 tree · zero dependencies, node ≥18 · MIT</footer>
+</main>
+</div>
+</body>
+</html>

package/AGENTS.template.md CHANGED Viewed

@@ -27,18 +27,28 @@ into the project's `AGENTS.md` automatically, so prefer that copy):
 2. Discover peers: `$BOARD agents`. There are no roles and no orchestrator —
    if you see work worth doing, do it or message someone about it.
 3. Send whenever you want — just a tool call, fire and forget:
-   ```powershell
-   $BOARD send --from <you> --to <peer> --body "<message>"
-   ```
-   On opencode prefer the `dm-send` tool (same thing, plus session routing).
+    ```powershell
+    $BOARD send --from <you> --to <peer> --body "<message>" [--subject "<mission>"] [--reply <msg-id>]
+    ```
+    Fanning work out ("assign N agents"): the DM *is* the task — `--to`
+    takes a comma list (`--to alice,bob,carol`, one copy each, shared batch
+    id). Put mission + scope + definition of done in the body; each agent
+    owns its scope, decides itself, and DMs a summary back.
+    On opencode prefer the `dm-send` tool (same thing, plus session routing).
 4. Read your mail often. Push arrives automatically on opencode; everywhere
-   else poll or block:
-   ```powershell
-   $BOARD inbox --from <you> [--after <msg-id>] [--json]
-   $BOARD listen --from <you> [--timeout 60000]
-   ```
-5. Reply with `send`/`dm-send` if needed, or continue current work if the DM
-   is unrelated. You decide — that is the whole coordination model.
+    else poll or block:
+    ```powershell
+    $BOARD inbox --from <you> [--after <msg-id>] [--json]
+    $BOARD listen --from <you> [--timeout 60000]
+    ```
+    Every DM stamps the sender's git rev: if your checkout is newer than the
+    rev on the DM, cited `file:line` numbers may be stale — re-read the file
+    before acting. Every send/inbox echoes `[board <path>]`: if two agents
+    see different boards, export `AGENTBOARD_DIR=<board>` so all sessions
+    share one.
+5. Reply with `send`/`dm-send` (`--reply <msg-id>` threads it) if needed, or
+    continue current work if the DM is unrelated. You decide — that is the
+    whole coordination model.
 Rules: one stable name per session, short factual messages, never post
 secrets (reference their location instead). No tasks, no claims, no holds.

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,45 @@
 # Changelog
+## 2.4.1 (unpublished)
+- Opencode watcher is now at-least-once: a failed `promptAsync` push (e.g.
+  into a stale session failing with `encrypted_content was not issued to
+  this caller`) releases the `delivered/<agent>/<msg>.json` marker, leaves
+  `cursors/<agent>.json` alone, and invalidates the stale
+  `agents/<agent>.json` sessionId so mail waits for pull until the live
+  session re-registers. The cursor advances only on success, so failed
+  pushes are retried instead of black-holed.
+- New `redeliver --from <you> (--id <msg-id> | --all)` recovers mail a dead
+  watcher already consumed: clears delivered markers and rewinds the cursor
+  so the next poll/push treats the message as fresh (the DM itself is never
+  touched — `inbox` always shows full history).
+## 2.4.0 (published 2026-09-21)
+- Broadcast send: `--to alice,bob,carol` (CLI) / comma-list `to`
+  (`dm-send` tool, `dm_send` MCP) fans one brief out to up to 20 agents —
+  one DM each, unique id, shared `batch` id. The DM *is* the task: documented
+  fan-out pattern (brief + scope + done-criteria, owners decide, summaries
+  back) in README, AGENTS.md block, and AGENTS.template.md.
+- Threading + staleness metadata: `--subject` / `--reply` (CLI flags,
+  `dm-send`/`dm_send` args) stored on every message and shown by
+  inbox/listen/hook/plugin; every send stamps the sender's git rev
+  (best-effort, omitted outside checkouts) so recipients spot stale
+  file:line numbers. Push footers nudge re-reading cited files vs rev.
+- Split-board visibility: `send`/`inbox`/`agents`/`register` echo
+  `[board <path>]` everywhere; empty inboxes name their board; drive-root
+  refusals quote the cwd and the walk-up bases tried (opencode tool tries
+  worktree, directory, then cwd). `doctor` prints board + AGENTBOARD_DIR
+  state + cwd + git rev.
+- Read commands never plant boards: `agents`/`inbox`/`listen` (CLI) and
+  `dm_inbox`/`dm_agents` (MCP) fail loudly with the resolved path when no
+  `board.json` is there, instead of showing an empty room.
+- Parallel-send hardening: unique message ids (4 random bytes), pid-tagged
+  atomic tmp+rename with one Windows AV-hold retry, verified with 6
+  concurrent senders.
+- `sync-embeds.mjs` keeps the global-install embeds in `bin/agentboard.js`
+  byte-identical to `opencode/tools/dm-send.js` + `opencode/plugins/dm-watch.js`.
 ## 2.3.0 (unpublished)
 - Board resolution walks up to the project board (CLI, hook helper, MCP

package/README.md CHANGED Viewed

@@ -59,9 +59,38 @@ agentboard listen --from bob --timeout 60000
 ```
 `send` has **no cooldown and no types** — `from`, `to`, `body` (max 8000
-chars). DMs to never-registered agents wait in `inbox` until they register.
-Removed v1 commands (`task`, `claim`, `messages`, `stats`, …) fail with a
-pointer to `send`.
+chars), plus optional `subject` (mission line) and `reply` (message id you
+are answering). DMs to never-registered agents wait in `inbox` until they
+register. Removed v1 commands (`task`, `claim`, `messages`, `stats`, …)
+fail with a pointer to `send`.
+## Fanning work out (the DM *is* the task)
+There is deliberately no task object. To "assign N agents", broadcast one
+brief and let each agent own its scope:
+```powershell
+# one call, one copy per recipient, shared batch id
+agentboard send --from ui-lead --to alice,bob,carol --subject "brief: borderless cards" --body "Audit your scope, drop decorative borders, DM me a summary."
+```
+Conventions that make this work (all agents already follow them via the
+AGENTS.md block):
+* **One DM = one brief.** Put the mission, scope (files/dirs), and
+  definition of done in the body. The recipient decides the details.
+* **Thread answers** with `send --from alice --to ui-lead --reply <brief-id> --body "...summary..."`.
+* **Re-read before flagging.** Every DM stamps the sender's git rev
+  (`inbox` shows `rev <short>`); if your checkout is newer than the rev
+  on the DM, the cited `file:line` numbers may be stale — read the file
+  before acting.
+* **Compare boards when empty.** Every `send`/`inbox`/`agents` echoes
+  `[board <path>]`. An empty inbox on the wrong board looks identical to
+  "no mail" — compare the path with the sender's.
+`--to` takes up to 20 recipients (deduped). Each copy gets a unique
+message id; fan-outs share a `batch` id so recipients can tell they got
+the same brief. `--subject` is capped at 120 chars.
 ## Inserted into context (opencode)
@@ -111,14 +140,20 @@ agentboard --help
 ## Troubleshooting
-- **Two agents see different boards** (every send echoes `[board <path>]`):
-  export `AGENTBOARD_DIR=<board>` so all sessions share one — for in-process
-  tools (opencode `dm-send`) set it where the harness process launches, or
-  pass `board` explicitly per call (`dm-send({..., board: "C:/proj/.agentboard"})`).
-  Writers refuse to auto-create a board at a drive root and fail loudly instead.
+- **Two agents see different boards** (every send/inbox/agents echoes
+  `[board <path>]` — compare them): export `AGENTBOARD_DIR=<board>` so all
+  sessions share one — for in-process tools (opencode `dm-send`) set it
+  where the harness process launches, or pass `board` explicitly per call
+  (`dm-send({..., board: "C:/proj/.agentboard"})`). Read commands
+  (`agents`/`inbox`/`listen`) never create a board: on a path with no
+  `board.json` they fail loudly with the resolved path instead of showing
+  an empty room. Writers refuse to auto-create a board at a drive root and
+  fail loudly instead (the error lists the walk-up bases it tried).
 - **`doctor` reports FAIL**: re-run `agentboard init --harness <name>` (merges,
   never overwrites your own hooks), then follow the printed follow-ups
-  (trust approvals, `AGENTBOARD_AGENT`, restarts).
+  (trust approvals, `AGENTBOARD_AGENT`, restarts). `doctor` also prints the
+  resolved board, `AGENTBOARD_DIR` state, cwd, and git rev to make
+  split-board diagnosis one command.
 ## Safety notes / trust boundary
@@ -137,9 +172,15 @@ agentboard --help
 ## Publishing (maintainer)
 ```powershell
-npm test          # 88 checks, all must pass
+npm test          # smoke + harness checks, all must pass
 npm publish       # ships bin/ + opencode/ + docs (see "files" in package.json)
 ```
+`sync-embeds.mjs` (repo root, dev-only) re-embeds
+`opencode/tools/dm-send.js` + `opencode/plugins/dm-watch.js` into
+`bin/agentboard.js` for global installs — run it after editing either file
+and verify with `npm test`. `init` prefers the repo files when run from a
+checkout, so the embed only matters for `npm i -g` installs.
 After publishing, projects can skip the checkout entirely:
 `npm i -g @eamonpluto/agentboard` then `agentboard init --harness <name> --portable`.

package/bin/agentboard-hook.js CHANGED Viewed

@@ -79,8 +79,8 @@ function refuseDriveRootBoard(root, args) {
   if (exists) return;
   if (path.dirname(root) === path.parse(root).root) {
     fail(
-      `refusing to create a board at drive root ${root} — no project board found above cwd. ` +
-        `Pass --board <path> or set AGENTBOARD_DIR.`
+      `refusing to create a board at drive root ${root} — no project board found above cwd "${process.cwd()}". ` +
+        `Run from your project (the dir containing .agentboard/), pass --board <absolute path to .agentboard>, or set AGENTBOARD_DIR.`
     );
   }
 }
@@ -154,9 +154,16 @@ function readStdinSoon(ms) {
 }
 function formatBody(items, hasMore) {
-  const lines = items.map((m) => `[DM from ${m.from} @ ${m.at || "unknown time"}]\n${m.body}`);
+  const lines = items.map((m) => {
+    let head = `[DM from ${m.from} @ ${m.at || "unknown time"}`;
+    if (m.rev) head += ` (rev ${m.rev})`;
+    if (m.batch) head += ` [batch ${m.batch}]`;
+    if (m.replyTo) head += ` re: ${m.replyTo}`;
+    head += "]";
+    return head + (m.subject ? `\nsubj: ${m.subject}` : "") + `\n${m.body}`;
+  });
   let text = lines.join("\n\n");
-  const footer = `\n\n(Reply with a DM to the sender if needed, or continue current work if unrelated. ${items.length} new message(s)${hasMore ? " — more waiting, will follow next turn" : ""}.)`;
+  const footer = `\n\n(Reply with a DM to the sender if needed, or continue current work if unrelated. ${items.length} new message(s)${hasMore ? " — more waiting, will follow next turn" : ""}. Re-read cited files vs your checkout before flagging — the rev above tells you if the sender's file:line numbers are stale.)`;
   if ((text + footer).length > MAX_REASON_CHARS) {
     text = (text + footer).slice(0, MAX_REASON_CHARS - 20) + "\n…[truncated]";
     return text;
@@ -213,7 +220,8 @@ async function cmdSessionStart(args) {
   if (items.length > 0) {
     console.log(`agent-board: registered ${agent}${sessionId ? ` (session ${sessionId})` : ""}, ${items.length} waiting DM(s):\n`);
     for (const m of items) {
-      console.log(`[${m.id}] from ${m.from} @ ${m.at}\n${m.body}\n`);
+      const extra = `${m.subject ? `\nsubj: ${m.subject}` : ""}${m.rev ? ` (rev ${m.rev})` : ""}${m.batch ? ` [batch ${m.batch}]` : ""}${m.replyTo ? ` re: ${m.replyTo}` : ""}`;
+      console.log(`[${m.id}] from ${m.from} @ ${m.at}${extra}\n${m.body}\n`);
     }
   } else {
     console.log(`agent-board: registered ${agent}${sessionId ? ` (session ${sessionId})` : ""}, inbox empty`);