crewbus 10.0.2 → 10.0.3

package/docs/TROUBLESHOOTING.md

@@ -1,25 +1,26 @@
-# Troubleshooting matrix
-
-Start with `crewbus doctor` — it prints the resolved board,
-`CREWBUS_DIR` state, cwd, and git rev, and exits 1 when wiring is broken.
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Two agents see different mail / empty inbox looks wrong | Split boards: each session resolved a different `.crewbus/` | Compare the `[board <path>]` echoes on `send`/`inbox`; converge with `export CREWBUS_DIR=<board>` (or per-call `--board <path>`) |
-| `no board at <path>` on `agents`/`inbox`/`listen` | Read commands never create boards (by design) | Run `crewbus init` (or `send`/`register`) at the project root first |
-| `drive root` refusal (`/.crewbus`, `C:\.crewbus`) | cwd resolution failed (detached harness worktree) | Pass an explicit `--board` path or set `CREWBUS_DIR`; see one Windows note below |
-| `wrong token` / auth failure | Token missing or from a different name | Tokens print once and never re-print — reuse the `register` output saved at claim time (or `token rotate --from <name>` with the current token); export `CREWBUS_TOKEN`; names are lowercase (`Alice` == `alice`) |
-| Push never arrives (non-opencode harness) | Hooks not trusted / harness not restarted after `init` | Re-run `crewbus init --harness <name>` (merges, never overwrites), approve MCP/trust prompts (`/hooks`, `/hooks-trust`), restart harness |
-| `doctor` FAIL on hooks/MCP entries | Wiring edited or installed for another harness | Re-run `init --harness <name>`, then follow the printed follow-ups |
-| Duplicate or replayed DMs | Two push paths racing, or pruned markers | Markers in `delivered/` + `cursors/` dedupe across restarts; `redeliver --from <name> --all` after re-registering a dead watcher; `prune` keeps surviving markers so cursors never replay |
-| `spawn` refuses a name | A live worker still holds it | `spawn-status --to <name>` to inspect; `spawn-kill` the stale worker; stale (dead-pid) names are reusable |
-| Sync diverges / old mail returns | Deletions don't replicate; mtime skew | `prune` stays local by design; sync converges on message union + newer-mtime presence — rerun `sync`, check clocks |
-| Bench budget missed in CI | Loaded runner, not a regression | Re-run; budgets are generous on purpose — only consistent misses across runs count |
-
-Windows note: detached `spawn` workers are killed as a whole process tree on
-Windows; elsewhere termination follows the recorded pid. Drive-root guards
-mention `C:\` because that is where a failed cwd resolution lands — the fix
-is the same on every OS: set `CREWBUS_DIR` explicitly.
-
-Still stuck? File a bug with the template in `.github/ISSUE_TEMPLATE/bug.md`
-including the `doctor` output and the `[board <path>]` echoes.
+# Troubleshooting matrix
+
+Start with `crewbus doctor` — it prints the resolved board,
+`CREWBUS_DIR` state, cwd, and git rev, and exits 1 when wiring is broken.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Two agents see different mail / empty inbox looks wrong | Split boards: each session resolved a different `.crewbus/` | Compare the `[board <path>]` echoes on `send`/`inbox`; converge with `export CREWBUS_DIR=<board>` (or per-call `--board <path>`) |
+| `no board at <path>` on `agents`/`inbox`/`listen` | Read commands never create boards (by design) | Run `crewbus init` (or `send`/`register`) at the project root first |
+| `drive root` refusal (`/.crewbus`, `C:\.crewbus`) | cwd resolution failed (detached harness worktree) | Pass an explicit `--board` path or set `CREWBUS_DIR`; see one Windows note below |
+| Group has one member like `cam-1-cam-2-cam-3` | PowerShell array-splatted an unquoted `--add a,b,c` (npm shim rejoins with spaces) | Quote comma lists on PowerShell: `--add "cam-1,cam-2,cam-3"` (same for `--to`, `--to-group`). List flags also accept whitespace separation, so a space-joined list still parses as several names |
+| `wrong token` / auth failure | Token missing or from a different name | Tokens print once and never re-print — reuse the `register` output saved at claim time (or `token rotate --from <name>` with the current token); export `CREWBUS_TOKEN`; names are lowercase (`Alice` == `alice`) |
+| Push never arrives (non-opencode harness) | Hooks not trusted / harness not restarted after `init` | Re-run `crewbus init --harness <name>` (merges, never overwrites), approve MCP/trust prompts (`/hooks`, `/hooks-trust`), restart harness |
+| `doctor` FAIL on hooks/MCP entries | Wiring edited or installed for another harness | Re-run `init --harness <name>`, then follow the printed follow-ups |
+| Duplicate or replayed DMs | Two push paths racing, or pruned markers | Markers in `delivered/` + `cursors/` dedupe across restarts; `redeliver --from <name> --all` after re-registering a dead watcher; `prune` keeps surviving markers so cursors never replay |
+| `spawn` refuses a name | A live worker still holds it | `spawn-status --to <name>` to inspect; `spawn-kill` the stale worker; stale (dead-pid) names are reusable |
+| Sync diverges / old mail returns | Deletions don't replicate; mtime skew | `prune` stays local by design; sync converges on message union + newer-mtime presence — rerun `sync`, check clocks |
+| Bench budget missed in CI | Loaded runner, not a regression | Re-run; budgets are generous on purpose — only consistent misses across runs count |
+
+Windows note: detached `spawn` workers are killed as a whole process tree on
+Windows; elsewhere termination follows the recorded pid. Drive-root guards
+mention `C:\` because that is where a failed cwd resolution lands — the fix
+is the same on every OS: set `CREWBUS_DIR` explicitly.
+
+Still stuck? File a bug with the template in `.github/ISSUE_TEMPLATE/bug.md`
+including the `doctor` output and the `[board <path>]` echoes.

package/docs/VERSION_SKEW.md

@@ -1,6 +1,6 @@
 # Version skew (mixed-relay operation)
 
-How crewbus versions interoperate. Evidence: `package.json:2` (`10.0.0`),
+How crewbus versions interoperate. Evidence: `package.json:2` (`10.0.3`),
 `CHANGELOG.md` (10.0.0 2026-10-08; 7.0.0 2026-10-05; 6.4.0–6.0.0; 4.1.0/4.0.0 baseline).
 Capabilities: `RELAY_CAPS` + `launch` per `packages/contracts/board-caps.json:6-8`.
 Cell behavior is the NEW side's verified behavior (`bin/lib/sync.js` refs);

package/documentation.html

@@ -65,7 +65,7 @@
 <main>
 
 <h1>crewbus</h1>
-<p class="sub">A zero-dependency local DM bus for AI coding agents — v10.0.1 · package <code>@eamonpluto/crewbus</code> · <a href="https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml"><img src="https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>
+<p class="sub">A zero-dependency local DM bus for AI coding agents — v10.0.2 · package <code>crewbus</code> · <a href="https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml"><img src="https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>
 <p class="sub">Lead audience: developers running <strong>mixed-harness crews</strong> (opencode, Claude Code, Codex, Antigravity, grok-build, Cursor). <code>package.json</code> is the release version source of truth; <code>board.json</code>'s <code>version: 2</code> is the board <em>schema</em> version, not the release.</p>
 
 <h2 id="what">1 · What it is</h2>
@@ -271,7 +271,7 @@ crewbus doctor                              # confirm all-ok</code></pre>
 <p><code>npm test</code> runs 20 suites — smoke + harness + compact + tokenfile + digest + control-plane + launch + web-launch + pair-api + web-panel + web-approot + client-runtime + runtime-wiring + desktop-sidecar + mobile-client + approvals (×3) + fault-injection + integration — all green. <code>npm run bench</code> asserts scale budgets and <code>npm run bench:load</code> the synthetic 10–10k load test separately. <code>sync-embeds.mjs</code> (repo root, dev-only) re-embeds the opencode tool + plugin into <code>bin/crewbus.js</code> for global installs — run it after editing either file (CI enforces <code>--check</code>).</p>
 
 <h2 id="publish">15 · Install &amp; publish</h2>
-<pre><code>npm i -g @eamonpluto/crewbus     # global install
+<pre><code>npm i -g crewbus     # global install
 crewbus init --harness &lt;name&gt; --portable   # portable wiring
 # maintainer: npm test && npm publish   (needs npm login + 2FA approval)</code></pre>
 
@@ -292,7 +292,7 @@ crewbus init --harness &lt;name&gt; --portable   # portable wiring
   <li><strong>3.0.0</strong> — token-bound identity (first claim mints, <code>--token</code>/<code>CREWBUS_TOKEN</code>; breaking); presence (<code>agents --active</code>); <code>prune</code> retention; <code>spawn</code> + <code>spawn-status</code>/<code>spawn-kill</code>; <code>ack</code>/<code>thread</code>/<code>inbox --unacked</code>; <code>web</code> dashboard; <code>stop --all</code>.</li>
   <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/crewbus</code>.</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>crewbus</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>

package/index.html

@@ -2600,7 +2600,7 @@ kbd {
   <div class="terminal-stage">
     <div class="terminal" role="img" aria-label="Terminal session: installing crewbus, registering a lead, and launching a multi-harness task">
       <div class="term-bar"><span class="term-dot r"></span><span class="term-dot y"></span><span class="term-dot g"></span><span class="term-title">terminal — multi-harness launch in 60 seconds</span></div>
-      <div class="term-body"><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">npm i -g @eamonpluto/crewbus</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus init</span> <span class="c-flag">--harness claude,antigravity,codex</span></div><div class="term-line"><span class="c-ok">board ready at ./.crewbus — multi-harness adapters &amp; hooks configured</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus register</span> <span class="c-flag">--from lead</span></div><div class="term-line"><span class="c-out">first claim wins — token minted (saved to logs/lead.token, mode 0600)</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus launch</span> <span class="c-flag">--from lead --harness claude,antigravity --model claude-3-7-sonnet --workers 2</span> <span class="c-str">"Verify auth flow and benchmark."</span></div><div class="term-line"><span class="c-ok">2 workers booted across 2 harnesses · replies thread back · ack to close loop</span> <span class="term-caret"></span></div></div>
+      <div class="term-body"><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">npm i -g crewbus</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus init</span> <span class="c-flag">--harness claude,antigravity,codex</span></div><div class="term-line"><span class="c-ok">board ready at ./.crewbus — multi-harness adapters &amp; hooks configured</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus register</span> <span class="c-flag">--from lead</span></div><div class="term-line"><span class="c-out">first claim wins — token minted (saved to logs/lead.token, mode 0600)</span></div><div class="term-line"><span class="c-prompt">$ </span><span class="c-cmd">crewbus launch</span> <span class="c-flag">--from lead --harness claude,antigravity --model claude-3-7-sonnet --workers 2</span> <span class="c-str">"Verify auth flow and benchmark."</span></div><div class="term-line"><span class="c-ok">2 workers booted across 2 harnesses · replies thread back · ack to close loop</span> <span class="term-caret"></span></div></div>
       <p class="term-cap">Real commands, real output shape — paste them as-is against any board.</p>
     </div>
   </div>
@@ -3314,8 +3314,8 @@ crewbus spawn --from lead --to alice,bob --subject "brief: cards" \
     <div class="cta-panel">
       <h2>Install crewbus. Brief your first crew today.</h2>
       <p class="lede">One package, one minute, six harnesses. MIT licensed, tested on Linux, macOS and Windows.</p>
-      <div class="install-box">npm i -g @eamonpluto/crewbus<br>crewbus init --harness opencode<br>crewbus register --from lead<br>crewbus doctor</div>
-      <p class="dim small" style="margin-top: 18px; position: relative;">Staying current is one command — <code>npm i -g @eamonpluto/crewbus@latest</code> — and boards carry a schema version, so old checkouts keep working. <a class="top-link" href="#top" style="margin-top: 0;">↑ Back to top</a></p>
+      <div class="install-box">npm i -g crewbus<br>crewbus init --harness opencode<br>crewbus register --from lead<br>crewbus doctor</div>
+      <p class="dim small" style="margin-top: 18px; position: relative;">Staying current is one command — <code>npm i -g crewbus@latest</code> — and boards carry a schema version, so old checkouts keep working. <a class="top-link" href="#top" style="margin-top: 0;">↑ Back to top</a></p>
       <p class="dim small" style="margin-top: 10px; position: relative;">Hacking on it? Clone the repo, run <code>npm test</code>, and read the module map — MIT licensed, zero dependencies, no build step.</p>
       <div class="btn-row" style="justify-content: center;">
         <a class="btn btn-primary" href="documentation.html">Read the manual</a>
@@ -3361,11 +3361,11 @@ crewbus spawn --from lead --to alice,bob --subject "brief: cards" \
             <li><a href="https://github.com/eamonpluto/crewbus">GitHub</a></li>
             <li><a href="https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml">CI: Linux · macOS · Windows</a></li>
             <li><a href="CHANGELOG.md">Changelog</a></li>
-            <li><a href="https://www.npmjs.com/package/@eamonpluto/crewbus">@eamonpluto/crewbus</a></li>
+            <li><a href="https://www.npmjs.com/package/crewbus">crewbus</a></li>
           </ul>
         </div>
       </div>
-      <span>crewbus · one primitive: message another agent · MIT · package <code>@eamonpluto/crewbus</code></span>
+      <span>crewbus · one primitive: message another agent · MIT · package <code>crewbus</code></span>
       <span>v10.0.2 · zero dependencies · Node 18+</span>
     </footer>
   </div>

package/opencode/plugins/dm-watch.js

@@ -65,6 +65,13 @@ export const DmWatchPlugin = async ({ client, directory }) => {
   const deliveredDir = path.join(root, "delivered");
 
   const agentToSession = new Map(); // agent -> sessionID
+  const sessionMeta = new Map(); // agent -> { sessionID, confirmedAt }
+  // A mapped session is proof of life only while fresh: entries age out
+  // after TTL without a confirmed delivery or re-registration, so dead
+  // workers stop being heartbeated (and stop reading "active") instead
+  // of lingering forever. Their mail then waits for pull until the live
+  // session re-registers — the same fallback as a refused push.
+  const SESSION_TTL_MS = 30 * 60 * 1000;
   const processed = new Set(); // "<agent>/<msgId>"
   const lastBeat = new Map(); // agent -> epoch ms of last presence write
 
@@ -97,7 +104,14 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     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);
+      if (doc && doc.name && doc.sessionId) {
+        agentToSession.set(doc.name, doc.sessionId);
+        const meta = sessionMeta.get(doc.name);
+        if (!meta || meta.sessionID !== doc.sessionId) {
+          // (Re)registration: a new session id is fresh proof of life.
+          sessionMeta.set(doc.name, { sessionID: doc.sessionId, confirmedAt: Date.now() });
+        }
+      }
     }
   }
 
@@ -117,23 +131,15 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     if (prev && prev.lastSeen && now - new Date(prev.lastSeen).getTime() < 60000) return;
     const at = new Date().toISOString();
     try {
-      fs.writeFileSync(p, JSON.stringify({
-        name: agent,
-        firstSeen: (prev && prev.firstSeen) || at,
-        lastSeen: at,
-        sessionId: (prev && prev.sessionId) || undefined,
-        lastDir: (prev && prev.lastDir) || undefined,
-        spawnedPid: (prev && prev.spawnedPid) || undefined,
-        spawnedAt: (prev && prev.spawnedAt) || undefined,
-        spawnedBy: (prev && prev.spawnedBy) || undefined,
-        briefId: (prev && prev.briefId) || undefined,
-        spawnedWorktree: (prev && prev.spawnedWorktree) || undefined,
-        spawnedBranch: (prev && prev.spawnedBranch) || undefined,
-        spawnedLifetime: (prev && prev.spawnedLifetime) || undefined,
-        token: (prev && prev.token) || undefined,
-        tokenHash: (prev && prev.tokenHash) || undefined,
-        salt: (prev && prev.salt) || undefined,
-      }, null, 2) + "\n");
+      // Merge over prev, never enumerate (see mergeAgentDoc in
+      // bin/lib/identity.js — this file is standalone so the merge is
+      // inlined): a heartbeat must not drop fields it doesn't own.
+      const merged = { ...(prev && typeof prev === "object" ? prev : {}) };
+      for (const [k, v] of Object.entries({ name: agent, firstSeen: (prev && prev.firstSeen) || at, lastSeen: at })) {
+        if (v === undefined) delete merged[k];
+        else merged[k] = v;
+      }
+      fs.writeFileSync(p, JSON.stringify(merged, null, 2) + "\n");
     } catch {}
   }
 
@@ -328,6 +334,10 @@ export const DmWatchPlugin = async ({ client, directory }) => {
         await client.session.prompt({ path: { id: sessionID }, body: { parts: [{ type: "text", text }] } });
       }
       advanceCursor(agent, msg.id);
+      // A completed push is the only proof of life this watcher can
+      // observe directly — refresh the mapping TTL so live sessions
+      // stay pushable across idle stretches.
+      sessionMeta.set(agent, { sessionID, confirmedAt: Date.now() });
     } catch (e) {
       const detail = e && e.message ? e.message : String(e);
       releaseClaim(agent, msg.id);
@@ -360,6 +370,16 @@ export const DmWatchPlugin = async ({ client, directory }) => {
     for (const agent of agents) {
       const sessionID = agentToSession.get(agent);
       if (!sessionID) continue; // nobody live for this name — mail waits for pull
+      const meta = sessionMeta.get(agent);
+      if (!meta || meta.sessionID !== sessionID || Date.now() - meta.confirmedAt > SESSION_TTL_MS) {
+        // Stale mapping: no confirmed delivery and no re-registration
+        // within TTL. Drop it (clears the doc's sessionId too) so the
+        // agent stops reading "active" and its mail waits for pull until
+        // the live session re-registers.
+        invalidateSession(agent, sessionID);
+        sessionMeta.delete(agent);
+        continue;
+      }
       heartbeat(agent);
       let files = [];
       try {

package/opencode/tools/dm-send.js

@@ -382,22 +382,30 @@ export default tool({
     const tokenHint = minted.created ? ` identity '${from}' claimed, token ${minted.token} (set CREWBUS_TOKEN=${minted.token})` : "";
     const rev = gitRev(root);
     const at = new Date().toISOString();
-    // upsert sender with live session routing for the watcher plugin
+    // upsert sender with live session routing for the watcher plugin.
+    // Merge over prev, never enumerate: a hand-built record here once
+    // wiped spawn bookkeeping (spawnedPid/By, briefId) and roles off
+    // every worker that reported through this tool.
     const ap = path.join(root, "agents", from + ".json");
     let prev = null;
     try {
       prev = JSON.parse(fs.readFileSync(ap, "utf8"));
     } catch {}
-    writeJsonAtomic(ap, {
+    const merged = { ...(prev && typeof prev === "object" ? prev : {}) };
+    for (const [k, v] of Object.entries({
       name: from,
       firstSeen: (prev && prev.firstSeen) || new Date().toISOString(),
       lastSeen: new Date().toISOString(),
       sessionId: (context && context.sessionID) || (prev && prev.sessionId) || undefined,
       lastDir: context.worktree || context.directory || undefined,
-      token: (prev && prev.token) || undefined,
-      tokenHash: (prev && prev.tokenHash) || undefined,
-      salt: (prev && prev.salt) || undefined,
-    });
+    })) {
+      if (v === undefined) delete merged[k];
+      else merged[k] = v;
+    }
+    for (const k of Object.keys(merged)) {
+      if (merged[k] === undefined) delete merged[k];
+    }
+    writeJsonAtomic(ap, merged);
     const isAll = recipients.length === 1 && recipients[0] === "@all";
     const mirrorChannels = (batch) => {
       if (args.also_channel !== true) return "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewbus",
-  "version": "10.0.2",
+  "version": "10.0.3",
   "description": "Zero-dependency message bus for AI coding-agent crews: message another agent, inserted into context, just a tool call.",
   "type": "module",
   "bin": {