crewbus 10.0.2 → 10.0.3

package/bin/lib/spawn.js

@@ -161,25 +161,69 @@ export function parseAllowEnv(raw) { // line 4078
   return String(raw).split(",").map((s) => String(s).trim()).filter(Boolean).join(",");
 }
 
-export function buildSpawnPrompt({ name, from, subject, body, replyId, rev, cwd, root }) { // line 4090
+export function buildSpawnPrompt({ name, from, subject, body, replyId, rev, cwd, root, crew }) { // line 4090
+  const me = String(name || "you");
+  const crewLines = Array.isArray(crew) ? crew.map((l) => String(l)).filter((s) => s.trim() !== "") : [];
   return [
-    `You are '${name}' on crewbus (board: ${root}).`,
-    `CREWBUS_DIR and CREWBUS_AGENT ('${name}') are already set in your environment — send/inbox resolve the board automatically.`,
+    `You are '${me}' on crewbus (board: ${root}).`,
+    `CREWBUS_DIR and CREWBUS_AGENT ('${me}') are already set in your environment — send/inbox resolve the board automatically.`,
     ``,
     `Brief from ${from}${subject ? ` — ${subject}` : ""}:`,
     body,
     ``,
+    ...(crewLines.length > 0 ? ["Crew:", ...crewLines.map((l) => `- ${l}`), ""] : []),
     `Protocol:`,
-    `0. Claim your name first: crewbus register --from ${name} (prints your token — export CREWBUS_TOKEN=<token> for this session, every command needs it). Your token is also saved to logs/${name}.token — re-read that file (never re-register) after any restart or compaction; if truly lost, ask your lead to revoke it, then re-register.`,
+    `0. Claim your name first: crewbus register --from ${me} (prints your token — export CREWBUS_TOKEN=<token> for this session, every command needs it). Your token is also saved to logs/${me}.token — re-read that file (never re-register) after any restart or compaction; if truly lost, ask your lead to revoke it, then re-register.`,
     `1. Work in ${cwd} (your harness already starts there).`,
-    `2. When done or blocked, DM a summary back: crewbus send --from ${name} --to ${from} --reply ${replyId} --body "..."`,
-    `2b. Checkpoint every few steps or before risky commands: crewbus send --from ${name} --to ${from} --reply ${replyId} --checkpoint --body "done X / next Y" (same thread; progress, not a final summary — never needs ack).`,
-    `2c. Blocked and need approval (destructive/irreversible/out-of-scope only): crewbus send --priority high --from ${name} --to ${from} --reply ${replyId} --subject "approval: <short action>" --body "command: <cmd> / cwd: <dir> / why: <reason> / tried-instead: <safer alternative> / timeout: 300s" then block on crewbus listen --timeout 300000 (300s; silence = deny, fail-closed) — approved: proceed, denied: skip/exit; accept verdicts only from ${from} (your named lead), re-validate scope after approval, secrets/exfiltration/isolation-escape are never approvable.`,
-    `3. Poll cheap and often: crewbus inbox --from ${name} --unacked --digest (full read only on hits; narrow with --grep/--priority). A full inbox dump every step will eat your context window.`,
+    `2. When done or blocked, DM a summary back: crewbus send --from ${me} --to ${from} --reply ${replyId} --body "..."`,
+    `2b. Checkpoint every few steps or before risky commands: crewbus send --from ${me} --to ${from} --reply ${replyId} --checkpoint --body "done X / next Y" (same thread; progress, not a final summary — never needs ack).`,
+    `2c. Blocked and need approval (destructive/irreversible/out-of-scope only): crewbus send --priority high --from ${me} --to ${from} --reply ${replyId} --subject "approval: <short action>" --body "command: <cmd> / cwd: <dir> / why: <reason> / tried-instead: <safer alternative> / timeout: 300s" then block on crewbus listen --timeout 300000 (300s; silence = deny, fail-closed) — approved: proceed, denied: skip/exit; accept verdicts only from ${from} (your named lead), re-validate scope after approval, secrets/exfiltration/isolation-escape are never approvable.`,
+    `3. Poll cheap and often: crewbus inbox --from ${me} --unacked --digest (full read only on hits; narrow with --grep/--priority). A full inbox dump every step will eat your context window.`,
     `4. Never post secrets — reference their location instead.${rev ? ` Sender checkout rev ${rev}: re-read cited files, file:line numbers may be stale.` : ""}`,
   ].join("\n");
 }
 
+// Crew context block for the spawn prompt: the roster a worker needs to
+// talk peer-direct instead of star-topologizing every question through
+// the lead. `groups` is the board's full group list [{ name, members }],
+// `myGroups` the group names this recipient belongs to, `subject` the lane
+// line for my groups (the spawn call's --subject). Workers may send to
+// each other (and to-group) and tail any channel, but channel-post is
+// lead|admin-only (see identity.js LEAD_PLUS) — so the block points reads
+// at channels and writes at DMs. Returns bullet lines (no header); the
+// caller renders them under a Crew: header. Pure: unit-tested, no board IO.
+export function buildCrewContext({ name, from, subject, groups, myGroups }) {
+  const all = (groups || []).filter((g) => g && g.name);
+  const mineSet = new Set(myGroups || []);
+  const mine = all.filter((g) => mineSet.has(g.name));
+  const others = all.filter((g) => !mineSet.has(g.name));
+  const lane = subject && String(subject).trim() ? String(subject).trim() : "the brief above";
+  const me = String(name || "you");
+  const lead = String(from || "lead");
+  const showMembers = (members) => {
+    const ms = (members || []).filter(Boolean).map(String);
+    return ms.slice(0, 8).join(",") + (ms.length > 8 ? "…" : "");
+  };
+  const out = [];
+  if (mine.length > 0) {
+    out.push(`your group(s): ${mine.map((g) => `${g.name} (${showMembers(g.members)})`).join("; ")} — your lane: ${lane}.`);
+  } else {
+    out.push(`you were spawned without a group (solo lane: ${lane}) — other agents are peers, not strangers.`);
+  }
+  if (others.length > 0) {
+    // Same one-liner as channels.js groupChannelName (grp-<group>, max 60).
+    out.push(`other groups on this board: ${others.map((g) => `${g.name} (${showMembers(g.members)})`).join("; ")} — their channels: ${others.map((g) => `grp-${g.name}`.slice(0, 60)).join(", ")}.`);
+  } else if (mine.length > 0) {
+    out.push(`no other groups on this board right now — discover live agents with: crewbus agents.`);
+  } else {
+    out.push(`discover who else is on this board with: crewbus agents (plus crewbus group list once groups exist).`);
+  }
+  out.push(`ask the group that owns a thing before asking ${lead}: crewbus send --from ${me} --to-group <group> --subject "..." --body "..." (reaches every member; ${lead} is for approvals and scope disputes only).`);
+  out.push(`read context freely: crewbus channel tail grp-<group> (a group's briefs + progress, reads need no token). Posting to channels needs lead rights — write everything via DMs.`);
+  out.push(`boot habit: crewbus agents + crewbus group list once, so you know who else is here.`);
+  return out;
+}
+
 export function buildSpawnTarget({ harness, cmd, model, auto, maxTurns, allowTools, cwd, name, promptPath, prompt, sessionId }) { // line 4114
   const quoteFree = (s) => String(s).replace(/"/g, "'");
   if (harness === "opencode") {
@@ -488,6 +532,7 @@ export function syncWorkerSession(d, name, logPath) { // respawn slice 1
     source = "preassigned-confirmed";
   }
   const doc = {
+    ...((prev && typeof prev === "object") ? prev : {}),
     name,
     harness: (prev && prev.harness) || undefined,
     spawnedPid: (prev && prev.spawnedPid) || undefined,
@@ -501,6 +546,12 @@ export function syncWorkerSession(d, name, logPath) { // respawn slice 1
     checkedMtime: tail.mtime,
     checkedAt: now,
   };
+  // Drop undefined so a re-scan never resurrects cleared fields and the
+  // doc stays a merge of the boot record (promptPath, model, cwd, cmd,
+  // respawnCount, …) plus the latest capture — never an enumeration.
+  for (const k of Object.keys(doc)) {
+    if (doc[k] === undefined) delete doc[k];
+  }
   try {
     fs.mkdirSync(path.join(d.root, "worker-sessions"), { recursive: true });
     writeJson(workerSessionPath(d, name), doc);
@@ -641,13 +692,19 @@ export function installCliToUserPath() {
   return { ok: true, binDir: userBinDir, addedToPath, detail };
 }
 
-export function bootWorker(d, spawnOpts, { to, id, from, subject, body, rev, logDir, budgetTokens, budgetMinutes, deadlineAt, spawnedWorktree, spawnedBranch, spawnedLifetime, sessionId }) { // line 4338
+export function bootWorker(d, spawnOpts, { to, id, from, subject, body, rev, logDir, budgetTokens, budgetMinutes, deadlineAt, spawnedWorktree, spawnedBranch, spawnedLifetime, sessionId, crew }) { // line 4338
   const { cwd, root } = spawnOpts;
   const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const prompt = buildSpawnPrompt({ name: to, from, subject, body, replyId: id, rev, cwd, root });
-  const promptPath = path.join(logDir, `${to}-${stamp}.prompt.md`);
-  fs.writeFileSync(promptPath, prompt + "\n");
-  const logPath = path.join(logDir, `${to}-${stamp}.log`);
+  const prompt = buildSpawnPrompt({ name: to, from, subject, body, replyId: id, rev, cwd, root, crew });
+    const promptPath = path.join(logDir, `${to}-${stamp}.prompt.md`);
+    fs.writeFileSync(promptPath, prompt + "\n");
+    const logPath = path.join(logDir, `${to}-${stamp}.log`);
+    // Boot metadata first: child stdout is often block-buffered (or never
+    // flushed at all on some harnesses), so the log must carry proof of
+    // life from minute one even if the worker prints nothing for hours.
+    try {
+      fs.writeFileSync(logPath, `# crewbus boot ${to} at ${new Date().toISOString()} brief ${id} harness ${spawnOpts.harness || "opencode"} prompt ${promptPath}\n`);
+    } catch {}
   const scrub = scrubChildEnv(process.env, spawnOpts);
   const childEnv = { ...scrub.env, CREWBUS_DIR: d.root, CREWBUS_AGENT: to };
   const shimDir = ensureBoardCliShim(d);
@@ -802,15 +859,22 @@ export function workerStatus(d, name, lines) { // line 4381
       } catch {}
     }
   }
-  let logPath = null;
-  let tail = [];
-  try {
-    const files = fs.readdirSync(path.join(d.root, "logs"))
-      .filter((f) => f.startsWith(`${name}-`) && f.endsWith(".log"))
-      .sort();
-    if (files.length > 0) {
-      logPath = path.join(d.root, "logs", files[files.length - 1]);
-      const content = fs.readFileSync(logPath, "utf8").split(/\r?\n/);
+    let logPath = null;
+    let logSize = null;
+    let logMtimeMs = null;
+    let tail = [];
+    try {
+      const files = fs.readdirSync(path.join(d.root, "logs"))
+        .filter((f) => f.startsWith(`${name}-`) && f.endsWith(".log"))
+        .sort();
+      if (files.length > 0) {
+        logPath = path.join(d.root, "logs", files[files.length - 1]);
+        try {
+          const st = fs.statSync(logPath);
+          logSize = st.size;
+          logMtimeMs = st.mtimeMs;
+        } catch {}
+        const content = fs.readFileSync(logPath, "utf8").split(/\r?\n/);
       if (content.length > 0 && content[content.length - 1] === "") content.pop();
       tail = content.slice(-Math.max(lines, 0));
     }
@@ -832,13 +896,15 @@ export function workerStatus(d, name, lines) { // line 4381
     budget = { tokensEst, budgetTokens: doc.budgetTokens ?? null, budgetMinutes: doc.budgetMinutes ?? null, elapsedMin, deadlineAt: doc.deadlineAt || null, overTokens, overMinutes, pastDeadline, exceeded: !!(overTokens || overMinutes || pastDeadline) };
   }
   const driver = cleanHarnessDriver(doc.spawnedHarness) || cleanHarnessDriver(ws && ws.harness) || undefined;
-  return {
-    name, known: true, pid: pid || null, alive, aliveVerified, pidStale, spawnedBy: doc.spawnedBy || null,
-    driver,
-    spawnedHarness: driver || undefined,
-    harnessSessionId: (ws && ws.harnessSessionId) || null,
-    respawnCount: (ws && ws.respawnCount) || 0,
-    briefId: doc.briefId || null, spawnedAt: doc.spawnedAt || null,
+    return {
+      name, known: true, pid: pid || null, alive, aliveVerified, pidStale, spawnedBy: doc.spawnedBy || null,
+      driver,
+      spawnedHarness: driver || undefined,
+      harnessSessionId: (ws && ws.harnessSessionId) || null,
+      respawnCount: (ws && ws.respawnCount) || 0,
+      briefId: doc.briefId || null, spawnedAt: doc.spawnedAt || null,
+      logSize, logMtimeMs,
+      logIdleMs: logMtimeMs !== null ? Math.max(0, Date.now() - logMtimeMs) : null,
     lifetime: doc.spawnedLifetime || "oneshot",
     worktree: doc.spawnedWorktree || null, branch: doc.spawnedBranch || null,
     lastSeen: doc.lastSeen || null, reply, acked, logPath, tail, budget,

package/bin/lib/store.js

@@ -204,7 +204,9 @@ export function chmodAgentFile(p) { // line 248
 }
 
 export function parseGroupList(raw) { // line 597
-  return String(raw || "").split(",").map((s) => String(s).trim().toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 40)).filter(Boolean);
+  // Commas and whitespace both separate (PowerShell can space-rejoin an
+  // unquoted a,b list); names themselves never contain spaces.
+  return String(raw || "").split(/[,\s]+/).map((s) => String(s).trim().toLowerCase().replace(/[^a-z0-9_.-]/g, "-").slice(0, 40)).filter(Boolean);
 }
 
 export function getFlag(args, flag) { // line 658

package/bin/lib/web.js

@@ -18,7 +18,7 @@ import http from "node:http";
 import { boardDir, requireBoard, getFlag, fail, writeJson, listJson, cleanWebName, readJson, gitRevForBoard, newId, MAX_SPAWN, MAX_BODY_CHARS } from "./store.js";
 import { readAgent, agentTokenMatches, authorizeCheck, mintToken, newSalt, hashToken, touchAgent } from "./identity.js";
 import { readDMs, readVisible, ackedIds, findMessageById, deliverDMs, parseRecipients } from "./mail.js";
-import { workerStatus, pidAlive, killWorkers, bootWorker, buildSpawnPrompt, buildSpawnTarget, formatSpawnCmd } from "./spawn.js";
+import { workerStatus, pidAlive, killWorkers, bootWorker, buildSpawnPrompt, buildSpawnTarget, formatSpawnCmd, installCliToUserPath, ensureBoardCliShim } from "./spawn.js";
 import { groupTelemetryData } from "./groups.js";
 import { httpJson } from "./sync.js";
 import { readChainRecords, verifyChainRecords, appendChainRecord, readHold, readBoardQuotas } from "./export.js";
@@ -32,6 +32,17 @@ export function escapeHtml(s) {
 
 export function boardSnapshot(d, activeWindowSec) {
   const cutoff = Date.now() - activeWindowSec * 1000;
+  // Liveness first: pid-bearing agents are active only while their process
+  // is verifiably alive (kill-0 + start-time guard inside workerStatus) —
+  // a fresh lastSeen alone proves nothing, because watcher heartbeats keep
+  // refreshing docs for long-dead sessions. Pid-less agents (humans, CLI
+  // peers) fall back to lastSeen freshness. Reuses the workers array below
+  // (no extra status syscalls).
+  const workers = listJson(d.agents)
+    .map((e) => e.data)
+    .filter((a) => a && a.name && typeof a.spawnedPid === "number")
+    .map((a) => workerStatus(d, a.name, 5));
+  const liveByName = new Map(workers.map((w) => [w.name, w.alive === true]));
   const agents = listJson(d.agents)
     .map((e) => e.data)
     .filter((x) => x && x.name)
@@ -42,12 +53,13 @@ export function boardSnapshot(d, activeWindowSec) {
       const { token, tokenHash, salt, ...safe } = a; // tokens never leave the server
       return {
         ...safe,
-        active: Date.parse(a.lastSeen) >= cutoff,
+        active: typeof a.spawnedPid === "number"
+          ? liveByName.get(a.name) === true
+          : Date.parse(a.lastSeen) >= cutoff,
         dmCount: visible.length,
         unacked: visible.filter((m) => !acked.has(m.id)).length,
       };
     });
-  const workers = agents.filter((a) => typeof a.spawnedPid === "number").map((a) => workerStatus(d, a.name, 5));
   const broadcasts = listJson(d.broadcast || path.join(d.root, "broadcast"))
     .map((e) => e.data)
     .filter((b) => b && b.id && b.from)
@@ -589,6 +601,7 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
         <div class="pop-path" id="pop-board-path">${e(boardPath)}</div>
         <button type="button" id="copy-board-btn" class="pop-btn"><svg class="btn-ic" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg> Copy Board Path</button>
         <button type="button" class="pop-btn" id="pop-pair-btn" style="margin-top:8px"><svg class="btn-ic" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="2" width="14" height="20" rx="2" ry="2"/><line x1="12" y1="18" x2="12.01" y2="18"/></svg> Pair Mobile Client (QR)…</button>
+        <button type="button" class="pop-btn" id="pop-install-cli-btn" style="margin-top:8px"><svg class="btn-ic" width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/></svg> Install 'crewbus' CLI in PATH</button>
       </div>
     </div>
 
@@ -646,8 +659,9 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
         <span>Search commands, workers, sections…</span>
         <kbd>Ctrl+K</kbd>
       </button>
-      <div class="topbar-right">
-        <label style="display:none">harness <select id="topbar-harness" aria-label="harness quick-pick"></select></label>
+        <div class="topbar-right">
+          <span id="poll-age" class="dim" title="age of the data on screen (Chrome throttles background tabs — a stale view is otherwise indistinguishable from a live one)"></span>
+          <label style="display:none">harness <select id="topbar-harness" aria-label="harness quick-pick"></select></label>
         <button type="button" id="inspector-toggle-btn" title="Toggle Inspector sidebar">Inspector ◨</button>
       </div>
     </header>
@@ -920,8 +934,8 @@ async function kill(names){
 }
 document.getElementById('killall').onclick=async function(){
   var rows=window.__workers||[];
-  var names=rows.filter(function(w){return w.known&&typeof w.pid==='number';}).map(function(w){return w.name;});
-  if(!names.length){say('no spawned workers');return;}
+    var names=rows.filter(function(w){return w.known&&w.alive===true;}).map(function(w){return w.name;});
+    if(!names.length){say('no live workers (kill needs a running pid)');return;}
   kill(names);
 };
 document.getElementById('ackall').onclick=async function(){
@@ -940,6 +954,8 @@ async function refresh(){
   try{
     var r=await fetch('/api/board',{cache:'no-store'});
     var s=await r.json();
+    window.__lastBoardPoll=Date.now();
+    updatePollAge();
     window.__workers=s.workers;
     var active=s.agents.filter(function(a){return a.active;}).length;
     var unacked=s.agents.reduce(function(n,a){return n+a.unacked;},0);
@@ -960,12 +976,12 @@ async function refresh(){
     document.getElementById('workers').innerHTML=s.workers.map(function(w){
       var tail=(w.tail||[]).slice(-3).map(function(l){return '<div class="log">'+esc(l)+'</div>';}).join('')||'<span class="dim">no log</span>';
       var rep=w.reply?esc(w.reply.id)+'<div class="dim">'+esc(w.reply.head)+'</div>':'—';
-      var btn=(w.known&&typeof w.pid==='number')?'<button class="danger" data-kill="'+esc(w.name)+'">kill</button>':'';
+      var btn=(w.known&&w.alive===true)?'<button class="danger" data-kill="'+esc(w.name)+'">kill</button>':'';
       return '<tr data-worker="'+esc(w.name)+'" class="worker-row"><td><b>'+esc(w.name)+'</b><div class="dim">by '+esc(w.spawnedBy||'?')+'</div></td><td>'+esc(stateOf(w))+'</td><td>'+(w.pid===null||w.pid===undefined?'—':esc(String(w.pid)))+'</td><td>'+rep+'</td><td>'+tail+'</td><td>'+btn+'</td></tr>';
     }).join('')||'<tr><td colspan="6" class="dim">no spawned workers</td></tr>';
     Array.prototype.forEach.call(document.querySelectorAll('[data-kill]'),function(b){b.onclick=function(){kill([b.getAttribute('data-kill')]);};});
     document.getElementById('agents').innerHTML=s.agents.map(function(a){
-      return '<tr><td><b>'+esc(a.name)+'</b></td><td>'+(a.active?'● active':'○ stale')+'</td><td>'+esc(a.lastSeen||'?')+'</td><td>'+esc(a.sessionId||'—')+'</td><td>'+a.dmCount+'</td><td>'+a.unacked+'</td></tr>';
+      return '<tr><td><b>'+esc(a.name)+'</b></td><td>'+(a.active?'● active':'○ stale')+'</td><td title="'+esc(a.lastSeen||'?')+'">'+esc(ago(a.lastSeen))+'</td><td>'+esc(a.sessionId||'—')+'</td><td>'+a.dmCount+'</td><td>'+a.unacked+'</td></tr>';
     }).join('')||'<tr><td colspan="6" class="dim">no agents yet</td></tr>';
     document.getElementById('bcast').innerHTML=s.broadcasts.map(function(b){
       var to=Array.isArray(b.to)?b.to.join(','):String(b.to||'');
@@ -1337,6 +1353,7 @@ function getActionIcon(act){
     case 'openfolder':return '<svg class="pal-ic" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/></svg>';
     case 'pairmobile':return '<svg class="pal-ic" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="5" y="2" width="14" height="20" rx="2" ry="2"/><line x1="12" y1="18" x2="12.01" y2="18"/></svg>';
     case 'refresh':return '<svg class="pal-ic" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21.5 2v6h-6M21.34 15.57a10 10 0 1 1-.57-8.38l5.67-5.67"/></svg>';
+    case 'installcli':return '<svg class="pal-ic" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/></svg>';
     default:return '';
   }
 }
@@ -1348,6 +1365,7 @@ function paletteSections(){
     {kind:'action',label:'Copy board path',action:'copyboard'},
     {kind:'action',label:'Open project folder…',action:'openfolder'},
     {kind:'action',label:'Pair mobile client (QR)…',action:'pairmobile'},
+    {kind:'action',label:'Install \'crewbus\' CLI in PATH',action:'installcli'},
     {kind:'action',label:'Refresh board state',action:'refresh'},
     {kind:'section',label:'Launch',id:'sec-launch'},
     {kind:'section',label:'Boards',id:'sec-boards'},
@@ -1417,6 +1435,7 @@ function paletteActivate(m){
       try{window.open('./pair.html','_blank','width=420,height=560');}catch(_){}
     }
     else if(m.action==='refresh'){refresh();}
+    else if(m.action==='installcli'){document.getElementById('pop-install-cli-btn').click();}
   }else if(m.kind==='section'){
     approotNavTo(m.id);
   }else{
@@ -1536,7 +1555,7 @@ function showInspector(name){
     +'<div class="dim">reply: '+rep+' · acked: '+esc(w.acked?'yes':'no')+' · session: '+esc(w.harnessSessionId||'—')+'</div>'
     +'<div class="log" style="margin-top:6px">'+tail+'</div>'
     +'<div style="margin-top:8px;display:flex;gap:6px;flex-wrap:wrap">'
-    +((w.known&&typeof w.pid==='number')?'<button class="danger" id="insp-kill">kill</button>':'')
+      +((w.known&&w.alive===true)?'<button class="danger" id="insp-kill">kill</button>':'')
     +(w.reply?'<button id="insp-ack">ack reply</button>':'')
     +'<button id="insp-respawn">respawn (CLI-only)</button></div>'
     +'<div class="dim" id="insp-respawn-cmd" style="margin-top:4px"></div>';
@@ -1647,6 +1666,27 @@ if(ppb){ppb.onclick=function(){
   try{window.parent.postMessage({type:'crewbus:open-pair'},'*');}catch(_){}
   try{window.open('./pair.html','_blank','width=420,height=560');}catch(_){}
 };}
+var picb=document.getElementById('pop-install-cli-btn');
+if(picb){picb.onclick=async function(){
+  picb.disabled=true;
+  picb.textContent='Installing CLI…';
+  try{
+    var r=await fetch('/api/install-cli',{method:'POST'});
+    var j=await r.json();
+    if(j&&j.ok){
+      say('CLI installed! '+(j.detail||''));
+      picb.textContent='CLI Installed (in PATH)';
+    }else{
+      say('Failed to install CLI: '+(j&&j.error||'unknown error'));
+      picb.textContent='Install Failed — Retry';
+      picb.disabled=false;
+    }
+  }catch(e){
+    say('Install error: '+e.message);
+    picb.textContent='Install Failed — Retry';
+    picb.disabled=false;
+  }
+};}
 document.getElementById('project-trigger').onclick=function(e){
   e.stopPropagation();
   var pop=document.getElementById('project-popover');
@@ -1726,9 +1766,15 @@ document.getElementById('launch-brief').addEventListener('keydown',function(e){
     document.getElementById('launch-go').click();
   }
 });
-loadLaunchMeta();
-refresh();
-setInterval(refresh,5000);
+  loadLaunchMeta();
+  refresh();
+  setInterval(refresh,5000);
+  // Data-age indicator: background tabs get their 5s poll throttled, so a
+  // stale view must say so instead of passing for live (see poll-age).
+  function agoMs(ms){var s=Math.max(0,Math.floor(ms/1000));if(s<60)return s+'s';var m=Math.floor(s/60);if(m<60)return m+'m';return Math.floor(m/60)+'h';}
+  function ago(iso){try{var t=Date.parse(iso);if(isNaN(t))return '?';return agoMs(Date.now()-t)+' ago';}catch(e){return '?';}}
+  function updatePollAge(){var el=document.getElementById('poll-age');if(!el)return;if(!window.__lastBoardPoll){el.textContent='not updated yet';return;}var age=Date.now()-window.__lastBoardPoll;var stale=age>15000;el.textContent=(stale?'STALE · ':'')+'updated '+agoMs(age)+' ago';el.style.color=stale?'var(--danger)':'';}
+  setInterval(updatePollAge,1000);
 </script>
 </body></html>`;
 }
@@ -1889,12 +1935,31 @@ export async function handleWebDashboardRoute(req, res, url, d) {
     res.end(JSON.stringify({ ok: false, error: "no lead.token found" }));
     return true;
   }
+  if (req.method === "POST" && url.pathname === "/api/install-cli") {
+    const ip = req.socket.remoteAddress || "";
+    const isLoop = ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1";
+    if (!isLoop) {
+      res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: "loopback only" }));
+      return true;
+    }
+    try {
+      const resInstall = installCliToUserPath();
+      res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+      res.end(JSON.stringify({ ok: true, ...resInstall }));
+    } catch (err) {
+      res.writeHead(500, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+      res.end(JSON.stringify({ ok: false, error: String(err && err.message ? err.message : err) }));
+    }
+    return true;
+  }
   return false;
 }
 
 export async function cmdWeb(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)");

package/docs/GROUPS.md

@@ -1,77 +1,102 @@
-# Groups, outcomes, races (Review §4.3)
-
-Groups are named recipient sets for variant briefs. Outcomes are native
-records — the interim workaround (one group per approach + `RESULT:`
-subjects + a verifier agent + a `gather --json` script + `spawn-kill`)
-is replaced by the commands below.
-
-## Curate + brief + reduce
-
-```sh
-crewbus group create team-a --add a1,a2,a3
-crewbus send --from lead --to-group team-a --subject "variant: regularity" --body "..."
-crewbus gather --batch <batch>   # briefs + replies + telemetry footer + contributing groups
-```
-
-`gather --batch` prints a telemetry footer
-(`msgs, ~tokens (chars/4), contributing groups`) and the same fields in
-`--json` (`contributingGroups`, `telemetry`).
-
-## Replies carry artifacts
-
-```sh
-crewbus send --from e1 --to lead --reply <brief-id> --artifact out/a1.json --body "done"
-```
-
-`--artifact <path-or-url>` (max 500 chars) is stored on the message and
-shown by `inbox` / `gather` / `thread`.
-
-## Verify, then record the result
-
-```sh
-crewbus ack --from lead --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
-crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from lead
-crewbus result show --group team-a
-crewbus result list [--group team-a] [--json]
-```
-
-`results/<group>.json` holds ONE record
-`{group, artifact, by, msgId, verifierOutput, at}` — first verified
-result wins. Only verified messages are recordable: the ack marker
-`acked/*/<msgId>.json` must carry `verified:true`, else recording fails
-unless `--force` (which prints a warning to stderr).
-
-## Race mode
-
-```sh
-crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
-crewbus race close --group team-a --from lead [--kill]
-```
-
-`race start` reports the winner (recorded result whose `msgId` is in the
-batch, else the first verified ack on a batch reply) or "no verified
-result yet". `--timeout` polls instead of checking once; there is no
-daemon. `race close` DMs "race closed by X" to every other member and,
-with `--kill`, terminates their spawned pids.
-
-## Status + telemetry
-
-```sh
-crewbus group status team-a [--json]      # running (pid alive), replies, verified, spend
-crewbus group telemetry team-a [--json]   # {messages, tokensEst, wallClockMs, members, verifiedCount}
-```
-
-Spend = message count + wall-clock since the group `createdAt` +
-token estimate (`chars/4` over member bodies+subjects). `createdAt` is
-backfilled from the group file mtime for pre-existing groups.
-
-## Attribution (agents in several groups)
-
-- A reply attributes via its chain: `--reply <msg-id>` → root brief →
-  batch → group(s) whose members appear in the transcript.
-- `gather --batch` shows `contributing groups` (groups with ≥1 message
-  from a member in the transcript).
-- `result record` **requires `--group` explicitly** — there is no
-  auto-assign. When an agent is in several groups, the recorder decides
-  which group the result counts for.
-
+# Groups, outcomes, races (Review §4.3)
+
+Groups are named recipient sets for variant briefs. Outcomes are native
+records — the interim workaround (one group per approach + `RESULT:`
+subjects + a verifier agent + a `gather --json` script + `spawn-kill`)
+is replaced by the commands below.
+
+## Curate + brief + reduce
+
+```sh
+crewbus group create team-a --add a1,a2,a3
+crewbus send --from lead --to-group team-a --subject "variant: regularity" --body "..."
+crewbus gather --batch <batch>   # briefs + replies + telemetry footer + contributing groups
+```
+
+`gather --batch` prints a telemetry footer
+(`msgs, ~tokens (chars/4), contributing groups`) and the same fields in
+`--json` (`contributingGroups`, `telemetry`).
+
+## Replies carry artifacts
+
+```sh
+crewbus send --from e1 --to lead --reply <brief-id> --artifact out/a1.json --body "done"
+```
+
+`--artifact <path-or-url>` (max 500 chars) is stored on the message and
+shown by `inbox` / `gather` / `thread`.
+
+## Verify, then record the result
+
+```sh
+crewbus ack --from lead --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
+crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from lead
+crewbus result show --group team-a
+crewbus result list [--group team-a] [--json]
+```
+
+`results/<group>.json` holds ONE record
+`{group, artifact, by, msgId, verifierOutput, at}` — first verified
+result wins. Only verified messages are recordable: the ack marker
+`acked/*/<msgId>.json` must carry `verified:true`, else recording fails
+unless `--force` (which prints a warning to stderr).
+
+## Race mode
+
+```sh
+crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
+crewbus race close --group team-a --from lead [--kill]
+```
+
+`race start` reports the winner (recorded result whose `msgId` is in the
+batch, else the first verified ack on a batch reply) or "no verified
+result yet". `--timeout` polls instead of checking once; there is no
+daemon. `race close` DMs "race closed by X" to every other member and,
+with `--kill`, terminates their spawned pids.
+
+## Status + telemetry
+
+```sh
+crewbus group status team-a [--json]      # running (pid alive), replies, verified, spend
+crewbus group telemetry team-a [--json]   # {messages, tokensEst, wallClockMs, members, verifiedCount}
+```
+
+Spend = message count + wall-clock since the group `createdAt` +
+token estimate (`chars/4` over member bodies+subjects). `createdAt` is
+backfilled from the group file mtime for pre-existing groups.
+
+## Attribution (agents in several groups)
+
+- A reply attributes via its chain: `--reply <msg-id>` → root brief →
+  batch → group(s) whose members appear in the transcript.
+- `gather --batch` shows `contributing groups` (groups with ≥1 message
+  from a member in the transcript).
+- `result record` **requires `--group` explicitly** — there is no
+  auto-assign. When an agent is in several groups, the recorder decides
+  which group the result counts for.
+
+## Cross-group collaboration
+
+Groups share one board, so any member can already read anything. The
+thing that decides whether groups actually collaborate is whether the
+brief tells them the map. Since v10.0.x every `spawn` brief carries a
+**Crew:** block (see `buildCrewContext` in `bin/lib/spawn.js`): your
+group(s) + members + lane, the other groups + members, their group
+channels, and the peer-DM norm. Conventions that block assumes:
+
+- **Peer-direct for questions.** `crewbus send --from you --to-group
+  <group> --subject "..." --body "..."` reaches every member of
+  another group. Ask the group that owns a thing first; the lead is
+  for approvals (`--priority high`) and scope disputes only.
+- **Channels are the shared read surface.** `crewbus channel tail
+  grp-<group>` shows a group's briefs + mirrored progress; reads need
+  no token. Channel *posting* is lead|admin-only, so workers write
+  via DMs, never via `channel post`.
+- **Boot habit.** `crewbus agents` + `crewbus group list` once at
+  start, so a worker knows who else is here. A worker that never runs
+  a discovery command will work star-topology through the lead — that
+  is a failure of the brief, not the worker.
+- **Scope questions stay lanes-first.** "Stay in your lane" prevents
+  collisions; "DM the group that owns a thing" prevents silos. A
+  brief should name both the boundary *and* the bridge.
+