@eamonpluto/agentboard 2.4.0 → 2.4.1

package/AGENTBOARD.html

@@ -54,7 +54,7 @@
 <main>
 
 <h1>agentboard</h1>
-<p class="sub">A zero-dependency local DM bus for AI coding agents — v2.3.0 · package <code>@eamonpluto/agentboard</code></p>
+<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>
@@ -76,10 +76,10 @@
 <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 }
+  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-8c2f86</code> (UTC timestamp + random suffix), ordered by <code>at</code> then <code>id</code>. Writes are atomic (write-temp-then-rename); delivery claims are atomic exclusive-creates, so concurrent agents and restarts never double-deliver.</p>
+<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>
@@ -87,13 +87,14 @@
                [--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 "..." [--session &lt;id&gt;]
+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). It echoes <code>sent &lt;id&gt; -&gt; &lt;to&gt; [board &lt;path&gt;]</code> so you always see which board you hit. 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).</li>
+  <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>
@@ -103,7 +104,7 @@ agentboard doctor [--harness &lt;list&gt;] [--board &lt;path&gt;]</code></pre>
 <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)</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>
@@ -122,7 +123,7 @@ agentboard doctor [--harness &lt;list&gt;] [--board &lt;path&gt;]</code></pre>
 </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)</code>, <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. Errors return <code>isError</code> results, never crashes.</p>
+<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>
@@ -146,7 +147,7 @@ agentboard-hook poll --from &lt;you&gt; --style &lt;s&gt; [--idle-after &lt;sec&
 <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. Steps it can't verify (Codex/grok MCP registration, trust grants) print as <code>info</code> reminders.</p>
+<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>
@@ -161,6 +162,15 @@ 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:
@@ -172,7 +182,7 @@ agentboard doctor                              # confirm all-ok</code></pre>
 <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, live <code>listen</code>, init, doctor, walk-up, drive-root guard) and <code>test/agentboard.harness.mjs</code> (MCP handshake/tools/overrides, hook styles/caps/idle/markers, plugin↔hook cross-delivery, all adapters incl. merge preservation, idempotency, auto-detect, portable entries). 88 checks, all green at v2.3.0.</p>
+<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
@@ -181,6 +191,7 @@ agentboard init --harness &lt;name&gt; --portable   # portable wiring
 
 <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>
@@ -188,7 +199,7 @@ agentboard init --harness &lt;name&gt; --portable   # portable wiring
   <li><strong>1.1.0</strong> — legacy task-board model.</li>
 </ul>
 
-<footer>agentboard manual · generated for the v2.3.0 tree · zero dependencies, node ≥18 · MIT</footer>
+<footer>agentboard manual · generated for the v2.4.0 tree · zero dependencies, node ≥18 · MIT</footer>
 
 </main>
 </div>

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Changelog
 
-## 2.4.0 (unpublished)
+## 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 —

package/bin/agentboard.js

@@ -192,7 +192,7 @@ 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", "--subject", "--reply", "--session", "--board", "--limit", "--after", "--timeout"]);
+const VALUE_FLAGS = new Set(["--from", "--to", "--body", "--subject", "--reply", "--replyTo", "--session", "--board", "--limit", "--after", "--timeout", "--id"]);
 
 // Comma-separated recipients: `--to alice,bob,carol` fans out one DM per
 // recipient (same body/subject, unique id each). Keeps the DM-only model
@@ -503,6 +503,13 @@ const OPENCODE_PLUGIN_DM_WATCH = `// .opencode/plugins/dm-watch.js — inject DM
 // mixing harnesses never get a message twice.
 // Polls every 1s; that poll is the source of truth (no fs.watch dependency).
 //
+// Delivery is at-least-once: the claim wins the race between watcher
+// instances, but the marker is released (and the cursor left alone) when
+// promptAsync throws — e.g. pushing into a stale session from yesterday
+// fails with \`encrypted_content was not issued to this caller\`. Stale
+// session mappings are then invalidated so mail waits for pull until the
+// live session re-registers, instead of being black-holed as delivered.
+//
 // Agents with no known session are skipped — their mail waits in the inbox
 // for pull (\`inbox --from <you>\`), so one idle session never steals another
 // agent's mail.
@@ -599,6 +606,40 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     }
   }
 
+  // Roll back a claim won above when the push itself fails: remove the
+  // on-disk marker and the in-memory entry so the next poll retries.
+  // The cursor is intentionally left alone here — it only advances on
+  // success, so a failed push never fast-forwards past undelivered mail.
+  function releaseClaim(agent, id) {
+    processed.delete(agent + "/" + id);
+    try {
+      fs.rmSync(deliveredMarker(agent, id), { force: true });
+    } catch {}
+  }
+
+  // promptAsync into a dead session throws provider errors like
+  // "[invalid_request_error] reasoning \`encrypted_content\` was not issued
+  // to this caller". Those mean the routing entry is stale, not the
+  // message — drop the mapping so mail waits for pull (\`inbox\`) until the
+  // live session re-registers via \`register --session\` or \`dm-send\`.
+  function isStaleSessionError(e) {
+    const s = String((e && e.message ? e.message : e) || "");
+    return /encrypted_content|invalid_request_error|unknown session|session not found|no such session|not issued to this caller/i.test(s);
+  }
+
+  function invalidateSession(agent, sessionID) {
+    agentToSession.delete(agent);
+    try {
+      const p = path.join(agentsDir, agent + ".json");
+      const doc = readJsonSafe(p);
+      if (doc && doc.sessionId === sessionID) {
+        delete doc.sessionId;
+        doc.lastSeen = new Date().toISOString();
+        fs.writeFileSync(p, JSON.stringify(doc, null, 2) + "\\n");
+      }
+    } catch {}
+  }
+
   // Cursor file shared with agentboard-hook: hook delivery moves it, and we
   // honor it (plus our markers) so mixed-harness agents never get doubles.
   // We also advance it on our own deliveries.
@@ -662,7 +703,6 @@ export const DmWatchPlugin = async ({ client, directory }) => {
 
   async function deliver(agent, sessionID, msg) {
     if (!claim(agent, msg.id, sessionID)) return;
-    advanceCursor(agent, msg.id);
     const text = formatDm(msg);
     try {
       if (client.session && typeof client.session.promptAsync === "function") {
@@ -670,13 +710,17 @@ export const DmWatchPlugin = async ({ client, directory }) => {
       } else if (client.session && typeof client.session.prompt === "function") {
         await client.session.prompt({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       }
+      advanceCursor(agent, msg.id);
     } catch (e) {
+      const detail = e && e.message ? e.message : String(e);
+      releaseClaim(agent, msg.id);
+      if (isStaleSessionError(e)) invalidateSession(agent, sessionID);
       try {
         await client.app.log({
           body: {
             service: "dm-watch",
             level: "warn",
-            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+            message: "DM push failed for " + agent + " (" + msg.id + "), released for retry: " + detail,
           },
         });
       } catch {}
@@ -1417,6 +1461,62 @@ async function cmdListen(args) {
   finish();
 }
 
+// ---------------------------------------------------------------------------
+// redeliver: recover mail a dead watcher consumed (claimed + cursor moved,
+// push failed). Clears delivered/<agent>/<id>.json markers and rewinds
+// cursors/<agent>.json so the next poll/push treats the message as fresh.
+// The DM itself is never touched — inbox always shows the full history.
+// ---------------------------------------------------------------------------
+
+function cmdRedeliver(args) {
+  const root = boardDir(args);
+  refuseDriveRootBoard(root, args);
+  const d = requireBoard(root);
+  const agent = resolveAgent(args, "agent");
+  const id = getFlag(args, "--id");
+  const all = args.includes("--all");
+  if (!id && !all) fail('missing --id <msg-id> (or --all to reset every delivery marker)');
+  if (id && all) fail('pass --id <msg-id> or --all, not both');
+  const order = readDMs(d, agent).map((m) => m.id);
+  let ids;
+  if (all) {
+    ids = order.slice();
+    if (ids.length === 0) fail(`no messages for ${agent}`);
+  } else {
+    if (!order.includes(id)) fail(`unknown message "${id}" for ${agent} (check inbox --from ${agent})`);
+    ids = [id];
+  }
+  for (const mid of ids) {
+    try {
+      fs.rmSync(path.join(d.delivered, agent, `${mid}.json`), { force: true });
+    } catch {}
+  }
+  // Rewind the cursor to the message before the earliest redelivered one so
+  // hook polls and the opencode watcher see it as fresh again. If the
+  // earliest redelivered message is the first in the log (or --all), drop
+  // the cursor entirely.
+  const cursorPath = path.join(d.root, "cursors", `${agent}.json`);
+  if (all) {
+    try {
+      fs.rmSync(cursorPath, { force: true });
+    } catch {}
+  } else {
+    const earliest = order.indexOf(ids[0]);
+    if (earliest <= 0) {
+      try {
+        fs.rmSync(cursorPath, { force: true });
+      } catch {}
+    } else {
+      writeJson(cursorPath, { lastId: order[earliest - 1], at: new Date().toISOString() });
+    }
+  }
+  if (ids.length === 1) {
+    console.log(`redelivered ${ids[0]} for ${agent} [board ${d.root}]`);
+  } else {
+    console.log(`redelivered ${ids.length} messages for ${agent} [board ${d.root}]`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // doctor: validate board + harness wiring
 // ---------------------------------------------------------------------------
@@ -1564,6 +1664,10 @@ Messaging (primitive — just a tool call, whenever you want):
   agentboard listen --from <you> [--timeout <ms>] [--json]
     (prints backlog, then blocks and prints new DMs as they arrive;
      opencode plugin injects into context automatically instead of polling)
+  agentboard redeliver --from <you> (--id <msg-id> | --all)
+    (recover mail a dead watcher consumed: clears delivered markers and
+     rewinds the cursor so the next poll/push treats it as fresh;
+     use after re-registering with the live session)
 
   agentboard doctor [--harness <list>] [--board <path>]
     (validate board + harness wiring; exit 1 with FAIL lines when broken)
@@ -1586,6 +1690,7 @@ async function main() {
     case "send": return cmdSend(rest);
     case "inbox": return cmdInbox(rest);
     case "listen": return await cmdListen(rest);
+    case "redeliver": return cmdRedeliver(rest);
     case "doctor": return cmdDoctor(rest);
     case undefined:
     case "-h":

package/opencode/plugins/dm-watch.js

@@ -12,6 +12,13 @@
 // mixing harnesses never get a message twice.
 // Polls every 1s; that poll is the source of truth (no fs.watch dependency).
 //
+// Delivery is at-least-once: the claim wins the race between watcher
+// instances, but the marker is released (and the cursor left alone) when
+// promptAsync throws — e.g. pushing into a stale session from yesterday
+// fails with `encrypted_content was not issued to this caller`. Stale
+// session mappings are then invalidated so mail waits for pull until the
+// live session re-registers, instead of being black-holed as delivered.
+//
 // Agents with no known session are skipped — their mail waits in the inbox
 // for pull (`inbox --from <you>`), so one idle session never steals another
 // agent's mail.
@@ -108,6 +115,40 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     }
   }
 
+  // Roll back a claim won above when the push itself fails: remove the
+  // on-disk marker and the in-memory entry so the next poll retries.
+  // The cursor is intentionally left alone here — it only advances on
+  // success, so a failed push never fast-forwards past undelivered mail.
+  function releaseClaim(agent, id) {
+    processed.delete(agent + "/" + id);
+    try {
+      fs.rmSync(deliveredMarker(agent, id), { force: true });
+    } catch {}
+  }
+
+  // promptAsync into a dead session throws provider errors like
+  // "[invalid_request_error] reasoning `encrypted_content` was not issued
+  // to this caller". Those mean the routing entry is stale, not the
+  // message — drop the mapping so mail waits for pull (`inbox`) until the
+  // live session re-registers via `register --session` or `dm-send`.
+  function isStaleSessionError(e) {
+    const s = String((e && e.message ? e.message : e) || "");
+    return /encrypted_content|invalid_request_error|unknown session|session not found|no such session|not issued to this caller/i.test(s);
+  }
+
+  function invalidateSession(agent, sessionID) {
+    agentToSession.delete(agent);
+    try {
+      const p = path.join(agentsDir, agent + ".json");
+      const doc = readJsonSafe(p);
+      if (doc && doc.sessionId === sessionID) {
+        delete doc.sessionId;
+        doc.lastSeen = new Date().toISOString();
+        fs.writeFileSync(p, JSON.stringify(doc, null, 2) + "\n");
+      }
+    } catch {}
+  }
+
   // Cursor file shared with agentboard-hook: hook delivery moves it, and we
   // honor it (plus our markers) so mixed-harness agents never get doubles.
   // We also advance it on our own deliveries.
@@ -171,7 +212,6 @@ export const DmWatchPlugin = async ({ client, directory }) => {
 
   async function deliver(agent, sessionID, msg) {
     if (!claim(agent, msg.id, sessionID)) return;
-    advanceCursor(agent, msg.id);
     const text = formatDm(msg);
     try {
       if (client.session && typeof client.session.promptAsync === "function") {
@@ -179,13 +219,17 @@ export const DmWatchPlugin = async ({ client, directory }) => {
       } else if (client.session && typeof client.session.prompt === "function") {
         await client.session.prompt({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       }
+      advanceCursor(agent, msg.id);
     } catch (e) {
+      const detail = e && e.message ? e.message : String(e);
+      releaseClaim(agent, msg.id);
+      if (isStaleSessionError(e)) invalidateSession(agent, sessionID);
       try {
         await client.app.log({
           body: {
             service: "dm-watch",
             level: "warn",
-            message: "DM wake failed for " + agent + ": " + (e && e.message ? e.message : String(e)),
+            message: "DM push failed for " + agent + " (" + msg.id + "), released for retry: " + detail,
           },
         });
       } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eamonpluto/agentboard",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Zero-dependency local DM bus for AI coding agents: message another agent, inserted into context, just a tool call.",
   "type": "module",
   "bin": {