crewbus 10.0.2 → 10.0.3

package/AGENTS.template.md

@@ -13,7 +13,7 @@ appends the right subsection automatically.
 You coordinate with other AI agents by messaging them directly — like Slack,
 minimal structure, figure it out yourselves.
 
-The CLI is run as (after `npm i -g .`, just `crewbus`; otherwise the full
+The CLI is run as (after `npm i -g crewbus`, just `crewbus`; otherwise the full
 path `node <this-checkout>/bin/crewbus.js` — `init` writes the real path
 into the project's `AGENTS.md` automatically, so prefer that copy):
 

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## Unreleased
+
+- Package is now published as unscoped `crewbus` (v10.0.2): `npm i -g crewbus`.
+
+## 10.0.3 (2026-10-10)
+
+PATCH RELEASE: Worker-record integrity, truthful presence, and multi-group collaboration in spawn briefs. No board-schema change (`board.json` stays v2); all prompt additions are backward-compatible (absent unless the spawn carries group/compute context).
+
+- **Spawn briefs carry a Crew: roster block**:
+  - Every `spawn` brief now names the worker's group(s) + members + lane, the other groups + members, and their group channels (`grp-<group>`).
+  - Ships the peer-DM norm with an explicit trigger (ask the group that owns a thing before asking the lead; lead stays for approvals/scope only), the read-channels/write-DMs distinction (channel-post is lead|admin-only), and a `crewbus agents` + `crewbus group list` boot habit.
+  - Documented as cross-group collaboration norms in `docs/GROUPS.md`.
+- **Agent-doc merge canonicalization**:
+  - New `mergeAgentDoc(prev, patch)` in `bin/lib/identity.js`; `touchAgent`, CLI `heartbeat`, and `register`'s mint path route through it.
+  - The `dm-send` tool and `dm-watch` plugin upserts merge over prev instead of enumerating — fixes spawned workers losing `spawnedPid`/`spawnedBy`/`briefId`/`role` (and with it: vanishing from `spawn-status`, unkillable workers, and silent role promotion) the moment they report.
+  - `syncWorkerSession` preserves binding fields (`promptPath`, model, cwd, cmd, respawn counts), which `respawn` needs.
+- **Truthful presence + session hygiene**:
+  - `boardSnapshot` gates pid-bearing agents on verified process liveness; pid-less agents keep lastSeen freshness.
+  - The watcher TTL-expires session mappings (30m without a confirmed delivery or re-registration) instead of heartbeating dead sessions forever.
+- **Observability**:
+  - Boot-metadata first line in every worker log; `workerStatus` surfaces `logSize`/`logMtimeMs`/`logIdleMs`.
+  - `doctor` gains a read-only dead-man scan (exited without reply, past deadline, alive-but-quiet) — informational, never FAIL.
+  - Dashboard shows data age + STALE banner, relative timestamps, alive-gated kill buttons; `spawn-status --all` lists pid-wiped workers as "no pid recorded" instead of dropping them.
+- **Windows ergonomics**: group lists split on whitespace too (unquoted `--add a,b,c` arriving space-rejoined now parses as several members); PowerShell quoting note in `docs/TROUBLESHOOTING.md`.
+
 ## 10.0.2 (2026-10-09)
 
 PATCH RELEASE: Target workspace CWD selector & persistence in Launch Studio, popover clarity, eliminated upload prompt, and Desktop v0.1.16 companion release.

package/README.md

@@ -1,4 +1,4 @@
-# crewbus v10.0.2 — DM bus
+# crewbus v10.0.3 — DM bus
 
 [![CI](https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml/badge.svg)](https://github.com/eamonpluto/crewbus/actions/workflows/ci.yml)
 
@@ -23,6 +23,13 @@ node $REPO/bin/crewbus.js <command>
 
 Or install globally:
 
+```sh
+npm i -g crewbus
+crewbus --help
+```
+
+Or from a local checkout (dev alternative):
+
 ```sh
 cd $REPO
 npm i -g .
@@ -48,7 +55,7 @@ env overrides below.)
 Layout: `board.json`, `agents/<name>.json`, `dm/<recipient>/<id>.json`,
 `delivered/<recipient>/<id>.json` (push markers, written by the plugin).
 
-Versions: `package.json` (currently 10.0.2) is the source of truth for the
+Versions: `package.json` (currently 10.0.3) is the source of truth for the
 release version. `board.json`'s `version: 2` is the **board schema version**
 (a different number on purpose — do not "align" them). New to the project?
 Start with `docs/QUICKSTART.md` (5 minutes).

package/bin/crewbus.js

@@ -42,11 +42,11 @@ import { execFileSync, spawn } from "node:child_process";
 // at top level so the import graph (store <- everyone; identity <- sync/spawn/
 // mail/groups/channels/web/relay/export) has no evaluation-order hazards.
 import { BOARD_VERSION, BROADCAST_AFTER, MAX_BODY_CHARS, MAX_RECIPIENTS, MAX_SPAWN, VALUE_FLAGS, boardDir, chmodAgentFile, cleanArtifact, cleanBranchPrefix, cleanChannelName, cleanGroupName, cleanPriority, cleanReply, cleanSenderType, cleanSubject, cleanWebName, dirs, ensureBoard, fail, findBoardUpward, getFlag, gitRevForBoard, listJson, newId, optionalAgent, parseDuration, readBoardMeta, readJson, refuseDriveRootBoard, requireBoard, resolveAgent, restArgs, sanitizeName, writeBoardMeta, writeExclusiveJson, writeJson, nextHlc, stampSyncDoc, hlcCompare, SEND_RATE_CAP, SEND_RATE_WINDOW_MS, MAX_FWD_DEPTH, DEDUPE_WINDOW_MS, webErr } from "./lib/store.js";
-import { VALID_ROLES, agentTokenMatches, assertMintWon, authorize, authorizeCheck, checkToken, cleanRole, countAgentRecords, defaultRoleForNew, ensureSender, hashToken, isHashRevoked, mergeSyncedAgent, mintToken, newSalt, readAgent, readBoardAcl, resolveToken, revokedPathForHash, roleOfRecord, sanitizeAgentForSync, stripAgentSecrets, timingSafeEqualStr, touchAgent, writeAgentFile, writeBoardAcl, isBoardFrozen } from "./lib/identity.js";
+import { VALID_ROLES, agentTokenMatches, assertMintWon, authorize, authorizeCheck, checkToken, cleanRole, countAgentRecords, defaultRoleForNew, ensureSender, hashToken, isHashRevoked, mergeAgentDoc, mergeSyncedAgent, mintToken, newSalt, readAgent, readBoardAcl, resolveToken, revokedPathForHash, roleOfRecord, sanitizeAgentForSync, stripAgentSecrets, timingSafeEqualStr, touchAgent, writeAgentFile, writeBoardAcl, isBoardFrozen } from "./lib/identity.js";
 import { saveTokenFile } from "./lib/tokenfile.js";
 import { CLIENT_TLS, SYNC_LWW, cleanSyncRel, clientInsecureFromArgs, crewSurvey, httpJson, readPemFlag, readSyncState, readTombstones, relayAuthEntries, relayCredFor, relayCredHeaders, setupClientTls, splitByWeight, syncRound, syncWalk, warnInsecureOnce, writeSyncState, writeTombstone, SYNC_SUBS, SYNC_UNION, RELAY_CAPS, SUB_CAP, SUB_CAP_NOTE, tombstoneIdForRel, readSyncDoc } from "./lib/sync.js";
 import { devicePath, isLoopbackHost, newDeviceCred, newPairToken, pairingPath, parseDeviceCred, readDevice, readRelayState, relaySecretFromArgs, remoteSpawn, requireRelayClientCert, requireRelaySecret, requireScope, tryAcquireFence, verifyOidcJwt, writeRelayState, relayStatePath, bearerFromReq, getOidcConfig, getOidcJwks, b64urlDecode, b64urlJson, jwsRawToDer, oidcGetJson, OIDC_SKEW_SEC, OIDC_JWKS_TTL_MS, OIDC_ALG_HASH, OIDC_EC_SIZE, deviceFromReq } from "./lib/relay.js";
-import { assertGitCheckout, bootRespawnedWorker, bootWorker, buildRespawnBrief, buildRespawnTarget, buildSpawnPrompt, buildSpawnTarget, formatSpawnCmd, isPidStale, killWorkers, maybeIsolate, parseAllowEnv, pidAlive, provisionBranch, provisionWorktree, readWorkerSession, requireAutoConfirm, sandboxPresent, scrubChildEnv, syncWorkerSession, workerStatus, worktreeStamp, defaultMaxTurnsFor } from "./lib/spawn.js";
+import { assertGitCheckout, bootRespawnedWorker, bootWorker, buildCrewContext, buildRespawnBrief, buildRespawnTarget, buildSpawnPrompt, buildSpawnTarget, formatSpawnCmd, isPidStale, killWorkers, maybeIsolate, parseAllowEnv, pidAlive, provisionBranch, provisionWorktree, readWorkerSession, requireAutoConfirm, sandboxPresent, scrubChildEnv, syncWorkerSession, workerStatus, worktreeStamp, defaultMaxTurnsFor, ensureBoardCliShim, installCliToUserPath } from "./lib/spawn.js";
 import { appendChainRecord, auditHmacKey, boardTotalBytes, chainFilePath, countChannels, dirSize, doExportToFile, enforceAgentQuota, enforceBytesQuota, enforceChannelQuota, holdActive, holdDocPath, holdRefusal, parseQuotaBytes, parseQuotaCount, readBackupInner, readBoardQuotas, readChainRecords, readHold, readSnapshotSchedule, resolveBackupKeyMaterial, setAuditForward, snapshotStamp, startAuditForwarder, verifyChainRecords, collectBoardFiles, encryptBackupPayload, decryptBackupPayload, rawKeyFromMaterial, deriveBackupKey, toAuditExport, spoolAuditEvent, postAuditEvent, auditSpoolDir, drainAuditSpool, enqueueAuditForward, signAuditRecord, chainRecordHash, AUDIT_FORWARD_URL, AUDIT_FORWARD_KEY } from "./lib/export.js";
 import { ackedIds, checkSendRateLimit, deliverDMs, enforceMaxChars, filterDigest, findDuplicateSend, findMessageById, heartbeat, isVerified, loadManifest, manifestPath, msgTimeMs, parseRecipients, printDigest, printMsg, readDMs, readVisible, recordBroadcastManifest, requireFanoutConfirm, resolveFwdDepth, runVerifier, verifyMessageSig, isHigh, signMessage, untrustedEnvelope, relTime, rateFilePath, broadcastTargets, readBroadcastsFor, formatTo, msgHeader, readAckMarker, splitCommand, readRecipientsFile } from "./lib/mail.js";
 import { batchReplyIds, collectBatch, contributingGroups, expandGroups, expandGroupsOrFail, gatherTelemetry, groupTelemetryData, heuristicSenderType, readGroup, ensureGroupCreatedAt, readResultRecord, writeResultRecord, findFirstVerifiedReply } from "./lib/groups.js";
@@ -591,22 +591,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 "";
@@ -731,6 +739,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
 
@@ -763,7 +778,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() });
+        }
+      }
     }
   }
 
@@ -783,23 +805,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 {}
   }
 
@@ -994,6 +1008,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);
@@ -1026,6 +1044,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 {
@@ -2023,24 +2051,20 @@ function cmdRegister(args) {
       // here (else anyone could self-mint admin). Warn, keep the default.
       process.stderr.write(`crewbus: warning: --role ignored (only an admin can grant roles; ask an admin to run register --from <admin> --for ${agent} --role ${String(roleWant).trim().toLowerCase()})\n`);
     }
-    const record = {
+    const record = mergeAgentDoc(prev, {
       name: agent,
       firstSeen: (prev && prev.firstSeen) || now,
       lastSeen: now,
       sessionId: session || (prev && prev.sessionId) || undefined,
       lastDir: process.cwd(),
-      spawnedPid: (prev && prev.spawnedPid) || undefined,
-      spawnedAt: (prev && prev.spawnedAt) || undefined,
-      spawnedBy: (prev && prev.spawnedBy) || undefined,
-      briefId: (prev && prev.briefId) || undefined,
       tokenHash: hashToken(fresh, salt),
       salt,
-      expiresAt: expiresAt !== undefined ? expiresAt : (serviceFlag ? null : ((prev && prev.expiresAt !== undefined) ? prev.expiresAt : undefined)),
+      expiresAt: expiresRaw !== undefined ? expiresAt : (serviceFlag ? null : ((prev && prev.expiresAt !== undefined) ? prev.expiresAt : undefined)),
       service: serviceFlag ? true : ((prev && prev.service !== undefined) ? prev.service : undefined),
       revokedAt: undefined,
       role: newRole,
       v, hlc,
-    };
+    });
     if (!prev) {
       // Fresh first-claim races (parallel registers): exactly one may win,
       // via atomic exclusive create. Losers fail loudly like a claimed name.
@@ -2472,7 +2496,11 @@ function cmdGroup(args) {
     const adds = [];
     const addRaw = getFlag(rest, "--add");
     if (addRaw) {
-      for (const part of String(addRaw).split(",")) {
+      // Split on commas AND whitespace: PowerShell array-splats an unquoted
+      // --add a,b,c into separate argv items that can rejoin with spaces
+      // (npm shims), so "cam-1 cam-2 cam-3" must parse as three names, not
+      // one joined member.
+      for (const part of String(addRaw).split(/[,\s]+/)) {
         if (part.trim() === "") continue;
         const clean = sanitizeName(part, "recipient");
         if (!adds.includes(clean)) adds.push(clean);
@@ -2840,6 +2868,17 @@ function cmdSpawn(args) {
   const toGroupRaw = getFlag(args, "--to-group");
   if (alsoChannel && (!toGroupRaw || !String(toGroupRaw).trim())) fail("--also-channel needs --to-group <g,...> (it mirrors the brief into each group's channel)");
   const groupNames = String(toGroupRaw || "").split(",").map((s) => String(s).trim().toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 40)).filter(Boolean);
+  // Crew roster for the prompt block (see buildCrewContext in lib/spawn.js):
+  // every group on the board with its members, so each worker learns the
+  // map — its own group, the other groups, and the peer-DM norms — at
+  // boot instead of discovering (or never discovering) the board alone.
+  const rosterGroups = [];
+  for (const e of listJson(d.groups)) {
+    const g = e && e.data;
+    if (g && g.name && Array.isArray(g.members)) rosterGroups.push({ name: g.name, members: g.members.slice() });
+  }
+  rosterGroups.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  const crewFor = (to) => buildCrewContext({ name: to, from, subject, groups: rosterGroups, myGroups: rosterGroups.filter((g) => g.members.includes(to)).map((g) => g.name) });
   const model = getFlag(args, "--model");
   const auto = args.includes("--auto");
   requireAutoConfirm(args);
@@ -2895,12 +2934,12 @@ function cmdSpawn(args) {
       const driver = harnesses[i % harnesses.length];
       const itemMaxTurns = maxTurnsNum !== undefined ? maxTurnsNum : ((driver === "claude" || driver === "grok") ? 50 : undefined);
       const itemSpawnOpts = { ...spawnOpts, harness: driver, maxTurns: itemMaxTurns, allowTools: driver === "claude" ? allowTools : undefined };
-      const previewPrompt = buildSpawnPrompt({ name: to, from, subject, body: body.trim(), replyId: previewBatch || "msg-<id>", rev, cwd, root });
+      const previewPrompt = buildSpawnPrompt({ name: to, from, subject, body: body.trim(), replyId: previewBatch || "msg-<id>", rev, cwd, root, crew: crewFor(to) });
       const t = buildSpawnTarget({ ...itemSpawnOpts, name: to, promptPath: `<logs>/${to}-<stamp>.prompt.md`, prompt: previewPrompt });
       const wtNote = worktreePrefix !== undefined ? ` worktree ../${to}-<stamp> (branch ${worktreePrefix}/${to}-<stamp>)` : branchPrefix !== undefined ? ` branch ${branchPrefix}/${to}-<stamp>` : "";
       console.log(`would spawn ${to} [${driver}] (${lifetime}) cwd ${cwd}${wtNote} cmd: ${formatSpawnCmd(t)} [board ${d.root}]`);
     });
-    console.log(`--- prompt (first worker) ---\n${buildSpawnPrompt({ name: recipients[0], from, subject, body: body.trim(), replyId: previewBatch || "msg-<id>", rev, cwd, root })}`);
+    console.log(`--- prompt (first worker) ---\n${buildSpawnPrompt({ name: recipients[0], from, subject, body: body.trim(), replyId: previewBatch || "msg-<id>", rev, cwd, root, crew: crewFor(recipients[0]) })}`);
     return;
   }
   // Direct (N-copy) path is forced here (every worker needs its own message
@@ -2934,7 +2973,7 @@ function cmdSpawn(args) {
       } else if (branchPrefix !== undefined) {
         workerBranch = provisionBranch(cwd, branchPrefix, to).branch;
       }
-      const r = bootWorker(d, { ...itemSpawnOpts, cwd: workerCwd }, { to, id, from, subject, body: body.trim(), rev, logDir, budgetTokens, budgetMinutes, deadlineAt, spawnedWorktree: workerWorktree, spawnedBranch: workerBranch, spawnedLifetime: lifetime });
+      const r = bootWorker(d, { ...itemSpawnOpts, cwd: workerCwd }, { to, id, from, subject, body: body.trim(), rev, logDir, budgetTokens, budgetMinutes, deadlineAt, spawnedWorktree: workerWorktree, spawnedBranch: workerBranch, spawnedLifetime: lifetime, crew: crewFor(to) });
       const where = workerWorktree ? ` worktree ${workerWorktree}` : workerBranch ? ` branch ${workerBranch}` : "";
       console.log(`spawned ${to} pid ${r.pid} [${driver}] (${lifetime}) log ${r.logPath} reply ${id}${where} [board ${d.root}]`);
     } catch (e) {
@@ -3366,9 +3405,12 @@ function cmdSpawnStatus(args) {
   const json = args.includes("--json");
   let names;
   if (args.includes("--all")) {
+    // Pid-bearing workers plus bookkept ones whose pid record was lost
+    // (e.g. an older dm-send wiped it): the latter still report via
+    // workerStatus as "no pid recorded" instead of vanishing silently.
     names = listJson(d.agents)
       .map((e) => e.data)
-      .filter((x) => x && x.name && typeof x.spawnedPid === "number")
+      .filter((x) => x && x.name && (typeof x.spawnedPid === "number" || x.spawnedBy || x.briefId))
       .map((x) => x.name)
       .sort();
   } else {
@@ -4303,14 +4345,43 @@ function cmdDoctor(args) {
   else info(`not a git checkout (sends omit rev)`);
 
   let ids = parseHarnessFlag(args);
-  if (ids.length === 0) {
-    if (meta && Array.isArray(meta.harnesses) && meta.harnesses.length > 0) ids = meta.harnesses.filter((h) => HARNESSES.includes(h));
-    else {
-      ids = detectHarnesses(cwd);
-      if (ids.length === 0) ids = ["generic"];
+    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) {
+    // Dead-man scan (read-only, board-local only — no cwd needed): the
+    // events a lead cannot see without polling — workers that exited
+    // without replying, passed deadlines, or went quiet while their pid
+    // is still alive. Informational only — never FAIL. Placed before the
+    // non-local early return so it runs for --board boards too.
+    try {
+      const dd = ensureBoard(root);
+      const found = [];
+      for (const e of listJson(path.join(root, "agents"))) {
+        const a = e && e.data;
+        if (!a || !a.name || typeof a.spawnedPid !== "number") continue;
+        let st = null;
+        try {
+          st = workerStatus(dd, a.name, 1);
+        } catch {
+          continue;
+        }
+        if (!st || !st.known) continue;
+        if (st.alive === false && a.briefId && !st.reply) {
+          found.push(`${a.name} exited with no reply to its brief — check its log (${st.logPath || "no log yet"})`);
+        } else if (st.budget && st.budget.exceeded) {
+          found.push(`${a.name} is past its deadline/budget — see spawn-status --to ${a.name}`);
+        } else if (st.alive === true && st.logIdleMs !== null && st.logIdleMs > 15 * 60 * 1000) {
+          found.push(`${a.name} alive but no log output for ${Math.round(st.logIdleMs / 60000)}m — possibly spinning; see spawn-status --to ${a.name}`);
+        }
+      }
+      for (const f of found.slice(0, 5)) info(`dead-man: ${f}`);
+      if (found.length > 5) info(`dead-man: …and ${found.length - 5} more — see spawn-status --all`);
+    } catch {}
+    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;
@@ -4426,16 +4497,16 @@ function cmdDoctor(args) {
         break;
     }
   }
-  // Reconcile hint (read-only): workers whose pids look recycled since a
-  // reboot read dead instead of running. Informational only — never FAIL.
-  try {
-    const stale = listJson(path.join(root, "agents"))
-      .map((e) => e.data)
-      .filter((x) => x && x.name && isPidStale(x.spawnedPid, x.spawnedAt))
-      .map((x) => x.name);
-    if (stale.length > 0) info(`${stale.length} worker(s) with stale pids (presumed dead after reboot): ${stale.slice(0, 5).join(",")}${stale.length > 5 ? "…" : ""} — see spawn-status --all; respawn to reboot`);
-  } catch {}
-  if (!process.env.CREWBUS_AGENT) info("CREWBUS_AGENT is unset — hooks need it to know who you are");
+    // Reconcile hint (read-only): workers whose pids look recycled since a
+    // reboot read dead instead of running. Informational only — never FAIL.
+    try {
+      const stale = listJson(path.join(root, "agents"))
+        .map((e) => e.data)
+        .filter((x) => x && x.name && isPidStale(x.spawnedPid, x.spawnedAt))
+        .map((x) => x.name);
+      if (stale.length > 0) info(`${stale.length} worker(s) with stale pids (presumed dead after reboot): ${stale.slice(0, 5).join(",")}${stale.length > 5 ? "…" : ""} — see spawn-status --all; respawn to reboot`);
+    } catch {}
+    if (!process.env.CREWBUS_AGENT) info("CREWBUS_AGENT is unset — hooks need it to know who you are");
   if (!process.env.CREWBUS_TOKEN) info("CREWBUS_TOKEN is unset — sends/reads as a claimed name need it");
   try {
     const legacy = fs.readdirSync(path.join(root, "agents")).filter((f) => f.endsWith(".json")).map((f) => {
@@ -4801,6 +4872,7 @@ async function cmdCrew(args) {
 async function cmdServe(args) {
   const root = boardDir(args);
   const d = requireBoard(root);
+  ensureBoardCliShim(d);
   const host = getFlag(args, "--host") || "127.0.0.1";
   const port = Number(getFlag(args, "--port") || 0);
   if (!(port >= 0 && port < 65536)) fail("--port must be 0-65535 (0 = random)");
@@ -6240,6 +6312,8 @@ Setup:
   crewbus init [--global] [--board <path>] [--force] [--no-opencode] [--portable]
                  [--harness opencode,claude,codex,antigravity,grok,cursor,generic]
     create board in ./.crewbus, write AGENTS.md block, install harness
+  crewbus install-cli
+    install standalone CLI wrapper to user PATH (~/.crewbus/bin)
     wiring (hooks + MCP config + notes). Without --harness, init applies the
     union of detected markers (.opencode/.claude/.codex/.agents/.grok/.cursor).
     init also pre-approves board-only bus I/O (crewbus MCP server +
@@ -7243,6 +7317,21 @@ async function cmdPoolResume(args) {
   }
 }
 
+function cmdInstallCli() {
+  const res = installCliToUserPath();
+  if (res.ok) {
+    console.log(`crewbus: standalone CLI wrappers written to ${res.binDir}`);
+    if (res.addedToPath) {
+      console.log(`crewbus: ${res.detail}`);
+      console.log(`crewbus: restart your terminal window, then type "crewbus" to verify`);
+    } else {
+      console.log(`crewbus: ${res.detail}`);
+    }
+  } else {
+    fail(`install-cli failed: ${res.detail || "unknown error"}`);
+  }
+}
+
 async function main() {
   const [, , cmd, ...rest] = process.argv;
   if (REMOVED.has(cmd)) {
@@ -7250,6 +7339,7 @@ async function main() {
   }
   switch (cmd) {
     case "init": return cmdInit(rest);
+    case "install-cli": return cmdInstallCli();
     case "register": return cmdRegister(rest);
     case "acl": return cmdAcl(rest);
     case "agents": return cmdAgents(rest);

package/bin/lib/groups.js

@@ -104,7 +104,10 @@ export function readGroup(d, name) {
 export function expandGroups(d, raw) {
   const out = [];
   if (raw === undefined || raw === null || String(raw).trim() === "") return out;
-  for (const part of String(raw).split(",")) {
+  for (const part of String(raw).split(/[,\s]+/)) {
+    // Group names carry no spaces (see cleanGroupName), so splitting on
+    // whitespace too is safe — and it saves PowerShell users whose
+    // unquoted --to-group a,b arrives space-rejoined (see cmdGroup --add).
     if (part.trim() === "") continue;
     const g = String(part).trim().toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 40);
     if (!g || g === "@all") throw new Error(`invalid group name "${part}"`);

package/bin/lib/identity.js

@@ -385,6 +385,25 @@ export function authorizeThrow(d, agent, action, scope) { // line 591
   return r;
 }
 
+// Canonical agent-doc merge: every writer starts from prev and applies
+// only its patch, so parallel writers (register, heartbeat, the dm-send
+// tool, the dm-watch plugin) can never drop fields they don't own (spawn
+// bookkeeping, tokens, roles). A patch key wins on any defined value —
+// including false/0/"" — so callers MUST pass undefined for no-change.
+// New agent-doc writers must use this or spread prev; never enumerate.
+export function mergeAgentDoc(prev, patch) {
+  const base = (prev && typeof prev === "object") ? { ...prev } : {};
+  const p = (patch && typeof patch === "object") ? patch : {};
+  for (const k of Object.keys(p)) {
+    if (p[k] === undefined) delete base[k];
+    else base[k] = p[k];
+  }
+  for (const k of Object.keys(base)) {
+    if (base[k] === undefined) delete base[k];
+  }
+  return base;
+}
+
 export function touchAgent(d, name, extra) { // line 2647
   const p = path.join(d.agents, `${name}.json`);
   const now = new Date().toISOString();
@@ -393,36 +412,13 @@ export function touchAgent(d, name, extra) { // line 2647
     prev = readJson(p);
   } catch {}
   const { v, hlc } = stampSyncDoc(prev);
-  const doc = {
+  const doc = mergeAgentDoc(prev, {
     name,
     firstSeen: (prev && prev.firstSeen) || now,
     lastSeen: now,
-    sessionId: (extra && extra.sessionId) || (prev && prev.sessionId) || undefined,
-    lastDir: (extra && extra.lastDir) || (prev && prev.lastDir) || undefined,
-    spawnedPid: (extra && extra.spawnedPid) || (prev && prev.spawnedPid) || undefined,
-    spawnedAt: (extra && extra.spawnedAt) || (prev && prev.spawnedAt) || undefined,
-    spawnedBy: (extra && extra.spawnedBy) || (prev && prev.spawnedBy) || undefined,
-    briefId: (extra && extra.briefId) || (prev && prev.briefId) || undefined,
-    budgetTokens: (extra && extra.budgetTokens) || (prev && prev.budgetTokens) || undefined,
-    budgetMinutes: (extra && extra.budgetMinutes) || (prev && prev.budgetMinutes) || undefined,
-    budgetSince: (extra && extra.budgetSince) || (prev && prev.budgetSince) || undefined,
-    deadlineAt: (extra && extra.deadlineAt) || (prev && prev.deadlineAt) || undefined,
-    spawnedWorktree: (extra && extra.spawnedWorktree) || (prev && prev.spawnedWorktree) || undefined,
-    spawnedBranch: (extra && extra.spawnedBranch) || (prev && prev.spawnedBranch) || undefined,
-    spawnedLifetime: (extra && extra.spawnedLifetime) || (prev && prev.spawnedLifetime) || undefined,
-    spawnedHarness: (extra && extra.spawnedHarness) || (prev && prev.spawnedHarness) || undefined,
-    spawnedEnvScrubbed: (extra && extra.spawnedEnvScrubbed) || (prev && prev.spawnedEnvScrubbed) || undefined,
-    token: (prev && prev.token) || undefined,
-    tokenHash: (prev && prev.tokenHash) || undefined,
-    salt: (prev && prev.salt) || undefined,
-    expiresAt: (extra && extra.expiresAt !== undefined ? extra.expiresAt : undefined) ?? (prev && prev.expiresAt !== undefined ? prev.expiresAt : undefined),
-    rotatedAt: (extra && extra.rotatedAt !== undefined ? extra.rotatedAt : undefined) ?? (prev && prev.rotatedAt !== undefined ? prev.rotatedAt : undefined),
-    service: (extra && extra.service !== undefined ? extra.service : undefined) ?? (prev && prev.service !== undefined ? prev.service : undefined),
-    offboarded: (extra && extra.offboarded !== undefined ? extra.offboarded : undefined) ?? (prev && prev.offboarded !== undefined ? prev.offboarded : undefined),
-    revokedAt: (extra && extra.revokedAt !== undefined ? extra.revokedAt : undefined) ?? (prev && prev.revokedAt !== undefined ? prev.revokedAt : undefined),
-    role: (extra && extra.role !== undefined ? extra.role : undefined) ?? (prev && prev.role !== undefined ? prev.role : undefined),
+    ...(extra || {}),
     v, hlc,
-  };
+  });
   writeAgentFile(d, name, doc);
   return doc;
 }

package/bin/lib/mail.js

@@ -9,7 +9,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { readJson, writeJson, listJson, newId, sanitizeName, fail, MAX_RECIPIENTS, BROADCAST_AFTER, MAX_FWD_DEPTH, SEND_RATE_CAP, SEND_RATE_WINDOW_MS, DEDUPE_WINDOW_MS, cleanPriority, cleanSubject, cleanReply, cleanArtifact, stampSyncDoc } from "./store.js";
-import { writeAgentFile, timingSafeEqualStr } from "./identity.js";
+import { writeAgentFile, timingSafeEqualStr, mergeAgentDoc } from "./identity.js";
 import { writeTombstone } from "./sync.js";
 import { boardHmacKey } from "./export.js";
 
@@ -733,34 +733,15 @@ export function heartbeat(d, name, minAgeMs) { // line 2689
     if (!(age >= minAgeMs)) return prev;
   }
   const { v, hlc } = stampSyncDoc(prev);
-  const doc = {
+  // Merge, never enumerate: heartbeat must not drop fields it doesn't own
+  // (spawn bookkeeping, tokens, roles — see mergeAgentDoc in identity.js).
+  const doc = mergeAgentDoc(prev, {
     name,
     firstSeen: (prev && prev.firstSeen) || now,
     lastSeen: now,
-    sessionId: (prev && prev.sessionId) || undefined,
     lastDir: process.cwd(),
-    spawnedPid: (prev && prev.spawnedPid) || undefined,
-    spawnedAt: (prev && prev.spawnedAt) || undefined,
-    spawnedBy: (prev && prev.spawnedBy) || undefined,
-    briefId: (prev && prev.briefId) || undefined,
-    budgetTokens: (prev && prev.budgetTokens) || undefined,
-    budgetMinutes: (prev && prev.budgetMinutes) || undefined,
-    budgetSince: (prev && prev.budgetSince) || undefined,
-    deadlineAt: (prev && prev.deadlineAt) || 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,
-    expiresAt: (prev && prev.expiresAt !== undefined ? prev.expiresAt : undefined),
-    rotatedAt: (prev && prev.rotatedAt !== undefined ? prev.rotatedAt : undefined),
-    service: (prev && prev.service !== undefined ? prev.service : undefined),
-    offboarded: (prev && prev.offboarded !== undefined ? prev.offboarded : undefined),
-    revokedAt: (prev && prev.revokedAt !== undefined ? prev.revokedAt : undefined),
-    role: (prev && prev.role !== undefined ? prev.role : undefined),
     v, hlc,
-  };
+  });
   try {
     fs.mkdirSync(d.agents, { recursive: true });
     writeAgentFile(d, name, doc);