crewbus 10.0.2 → 10.0.4

package/bin/lib/web.js

@@ -17,9 +17,9 @@ import path from "node:path";
 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 { groupTelemetryData } from "./groups.js";
+import { readDMs, readVisible, ackedIds, ackedIdSet, findMessageById, deliverDMs, parseRecipients } from "./mail.js";
+import { workerStatus, pidAlive, killWorkers, bootWorker, buildSpawnPrompt, buildSpawnTarget, formatSpawnCmd, installCliToUserPath, ensureBoardCliShim } from "./spawn.js";
+import { groupTelemetryData, collectBatch, gatherTelemetry, listBatches } from "./groups.js";
 import { httpJson } from "./sync.js";
 import { readChainRecords, verifyChainRecords, appendChainRecord, readHold, readBoardQuotas } from "./export.js";
 import { launchDrivers, detectHarnessBinaries, validateLaunchPlan, advertiseEnv, HARNESS_MODELS, getDiscoveredModels, refreshDiscoveredModels } from "./launch.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)
@@ -100,7 +112,18 @@ export function boardSnapshot(d, activeWindowSec) {
     .filter((x) => x && x.peer && typeof x.lastOk === "number")
     .sort((a, b) => String(a.peer).localeCompare(String(b.peer)))
     .map((p) => ({ peer: p.peer, lastOk: new Date(p.lastOk).toISOString() }));
-  return { board: d.root, at: new Date().toISOString(), agents, workers, broadcasts, recent: recent.slice(0, 30), ackedBy, groups, peers };
+  // Brief batch per worker (for the Crews brief/group column): the batch
+  // stamp on the worker's brief DM, else the brief id itself. Built from
+  // the full pre-slice message scan so capped feeds never lose the join.
+  const batchByBriefId = new Map();
+  for (const m of recent) {
+    if (m && m.id && !batchByBriefId.has(m.id)) batchByBriefId.set(m.id, m.batch || m.id);
+  }
+  const workersWithBatch = workers.map((w) => ({
+    ...w,
+    batch: w.briefId ? (batchByBriefId.get(w.briefId) || w.briefId) : undefined,
+  }));
+  return { board: d.root, at: new Date().toISOString(), agents, workers: workersWithBatch, broadcasts, recent: recent.slice(0, 30), ackedBy, groups, peers, briefs: listBatches(d) };
 }
 
 // Fleet console snapshots (served by `web`, all open reads like /api/board;
@@ -589,6 +612,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>
 
@@ -609,9 +633,10 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
 
     <div class="sidebar-heading">VIEWS</div>
     <nav id="approot-nav" aria-label="sections">
-      <button data-nav="sec-launch" class="active">Launch</button>
-      <button data-nav="sec-boards">Boards</button>
-      <button data-nav="sec-crews">Crews</button>
+        <button data-nav="sec-launch" class="active">Launch</button>
+        <button data-nav="sec-boards">Boards</button>
+        <button data-nav="sec-briefs">Briefs</button>
+        <button data-nav="sec-crews">Crews</button>
       <button data-nav="sec-fleet">Fleet</button>
       <button data-nav="sec-channels">Channels</button>
       <button data-nav="sec-triage">Triage</button>
@@ -646,8 +671,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>
@@ -756,15 +782,23 @@ details.tech-details summary{cursor:pointer;font-weight:500;user-select:none}
           <div class="card"><b id="c-peers">–</b><br>peers</div>
         </div>
         <h2>Recent activity</h2>
+        <div style="display:flex;gap:8px;margin-bottom:8px"><input id="feed-q" placeholder="filter route / message…" style="flex:1"><select id="feed-type"><option value="">all</option><option value="checkpoint">checkpoints</option><option value="final">final reports</option></select></div>
         <table><tr><th>id</th><th>route</th><th>message</th></tr><tbody id="recent"></tbody></table>
         <h2>Broadcasts</h2>
         <table><tr><th>id</th><th>from</th><th>to</th><th>subject</th><th>body</th></tr><tbody id="bcast"></tbody></table>
       </section>
 
+      <!-- SECTION: BRIEFS (ONE ROW PER FAN-OUT) -->
+      <section id="sec-briefs" data-section="Briefs" class="approot-hidden">
+        <h2>Briefs <span class="dim">one row per fan-out — click a row for its gathered thread</span></h2>
+        <table><tr><th>brief</th><th>workers</th><th>checkpoints</th><th>finals</th><th>acked</th><th>last activity</th></tr><tbody id="briefs"></tbody></table>
+        <div id="brief-thread"></div>
+      </section>
+
       <!-- SECTION: CREWS (WORKERS & TEAMS) -->
       <section id="sec-crews" data-section="Crews" class="approot-hidden">
         <h2>Workers <button id="killall" class="danger">kill all</button></h2>
-        <table><tr><th>worker</th><th>state</th><th>pid</th><th>reply</th><th>log tail</th><th></th></tr><tbody id="workers"></tbody></table>
+        <table><tr><th>worker</th><th>state</th><th>pid</th><th>brief / groups</th><th>reply</th><th>log tail</th><th></th></tr><tbody id="workers"></tbody></table>
         <h2>Agents</h2>
         <table><tr><th>name</th><th>presence</th><th>last seen</th><th>session</th><th>DMs</th><th>unacked</th></tr><tbody id="agents"></tbody></table>
         <h2>Groups</h2>
@@ -905,6 +939,10 @@ var _lt=document.getElementById('launch-token');
 if(_lt){_lt.oninput=function(){try{localStorage.setItem('ab-tok',this.value.trim());}catch(_){}var t=document.getElementById('tok');if(t)t.value=this.value.trim();markIdent();};}
 autoLoadOperatorCreds();
 function stateOf(w){if(!w.known)return 'unknown';if(w.reply)return w.acked?'done · acked':'done · reply waiting';if(w.alive===true)return 'running';if(w.alive===false)return 'exited · no reply';return 'no pid';}
+var _fq=document.getElementById('feed-q');
+if(_fq){_fq.oninput=function(){renderRecent();};}
+var _ft=document.getElementById('feed-type');
+if(_ft){_ft.onchange=function(){renderRecent()};}
 async function kill(names){
   var c=creds();
   if(!c.from||!c.token){say('set identity + token first');return;}
@@ -920,12 +958,11 @@ 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(){
-  var c=creds();
+document.getElementById('ackall').onclick=async function(){  var c=creds();
   if(!c.from||!c.token){say('set identity + token first');return;}
   if(!confirm('ack everything unacked for '+c.from+'?'))return;
   say('acking all for '+c.from+' …');
@@ -936,10 +973,43 @@ document.getElementById('ackall').onclick=async function(){
   }catch(e){say('ack failed: '+e.message);}
   refresh();
 };
+function renderRecent(){
+  var q=((document.getElementById('feed-q')||{}).value||'').toLowerCase();
+  var t=((document.getElementById('feed-type')||{}).value||'');
+  var known=window.__ackedBy||{};
+  var rows=(window.__recent||[]).filter(function(m){
+    if(t==='checkpoint'&&m.checkpoint!==true)return false;
+    if(t==='final'&&!(m.replyTo&&m.checkpoint!==true))return false;
+    if(!q)return true;
+    var to=Array.isArray(m.to)?m.to.join(','):String(m.to||'');
+    return (m.id+' '+(m.from||'')+' '+to+' '+(m.subject||'')+' '+(m.body||'')).toLowerCase().indexOf(q)!==-1;
+  });
+  document.getElementById('recent').innerHTML=rows.map(function(m){
+    var to=Array.isArray(m.to)?m.to.join(','):String(m.to||'');
+    var acks=(known[m.id]||[]).map(function(x){return '✓'+x;}).join(' ');
+    return '<tr><td>'+esc(m.id)+'</td><td>'+esc(m.from)+' → '+esc(short(to,40))+'</td><td>'+(m.subject?'<b>'+esc(m.subject)+'</b><br>':'')+esc(short(m.body,200))+'<div class="dim">'+(m.replyTo?('re: '+esc(m.replyTo)+' '):'')+(m.batch?('batch '+esc(m.batch)+' '):'')+esc(acks)+'</div></td></tr>';
+  }).join('')||'<tr><td colspan="3" class="dim">no messages yet</td></tr>';
+}
+async function showBrief(batch){
+  var box=document.getElementById('brief-thread');
+  box.innerHTML='<div class="dim">loading thread '+esc(batch)+'…</div>';
+  try{
+    var r=await fetch('/api/gather?batch='+encodeURIComponent(batch),{cache:'no-store'});
+    var g=await r.json();
+    if(!r.ok){box.innerHTML='<div class="dim">gather failed: '+esc(g.error||r.status)+'</div>';return;}
+    box.innerHTML='<h3>'+esc(short(batch,32))+' <span class="dim">'+g.briefs+' briefs · '+g.replies+' replies · ~'+g.telemetry.tokensEst+' tok</span></h3>'+g.items.map(function(m){
+      var kind=!m.replyTo?'<b>brief</b>':(m.checkpoint?'<span class="dim">checkpoint</span>':'<b>final'+(m.acked?' ✓':'')+'</b>');
+      var to=Array.isArray(m.to)?m.to.join(','):String(m.to||'');
+      return '<div class="card" style="margin:.5em 0"><div>'+kind+' <b>'+esc(m.from)+'</b> → '+esc(short(to,60))+' <span class="dim">'+esc(ago(m.at))+'</span></div>'+(m.subject?'<div><b>'+esc(m.subject)+'</b></div>':'')+'<div class="log" style="white-space:pre-wrap">'+esc(m.body)+'</div></div>';
+    }).join('');
+  }catch(e){box.innerHTML='<div class="dim">gather failed: '+esc(e.message)+'</div>';}
+}
 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,22 +1030,28 @@ 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>':'';
-      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>';
+      var btn=(w.known&&w.alive===true)?'<button class="danger" data-kill="'+esc(w.name)+'">kill</button>':'';
+      var wgroups=(s.groups||[]).filter(function(g){return (g.members||[]).indexOf(w.name)!==-1;}).map(function(g){return g.name;}).join(',');
+      var batch=w.batch||w.briefId||'—';
+      var bcell='<div class="dim">'+esc(short(batch,20))+'</div>'+(wgroups?esc(wgroups):'<span class="dim">solo</span>');
+      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>'+bcell+'</td><td>'+rep+'</td><td>'+tail+'</td><td>'+btn+'</td></tr>';
+    }).join('')||'<tr><td colspan="7" 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||'');
       return '<tr><td>'+esc(b.id)+'</td><td>'+esc(b.from)+'</td><td>'+esc(short(to,80))+'</td><td>'+esc(b.subject||'')+'</td><td>'+esc(short(b.body,140))+'</td></tr>';
     }).join('')||'<tr><td colspan="5" class="dim">no broadcasts</td></tr>';
-    document.getElementById('recent').innerHTML=s.recent.map(function(m){
-      var to=Array.isArray(m.to)?m.to.join(','):String(m.to||'');
-      var acks=(s.ackedBy[m.id]||[]).map(function(x){return '✓'+x;}).join(' ');
-      return '<tr><td>'+esc(m.id)+'</td><td>'+esc(m.from)+' → '+esc(short(to,40))+'</td><td>'+(m.subject?'<b>'+esc(m.subject)+'</b><br>':'')+esc(short(m.body,200))+'<div class="dim">'+(m.replyTo?('re: '+esc(m.replyTo)+' '):'')+(m.batch?('batch '+esc(m.batch)+' '):'')+esc(acks)+'</div></td></tr>';
-    }).join('')||'<tr><td colspan="3" class="dim">no messages yet</td></tr>';
+    window.__recent=s.recent||[];
+    window.__ackedBy=s.ackedBy||{};
+    renderRecent();
+    document.getElementById('briefs').innerHTML=(s.briefs||[]).map(function(b){
+      var ws=(b.workers||[]).join(',');
+      return '<tr data-batch="'+esc(b.batch)+'" class="brief-row"><td>'+(b.subject?'<b>'+esc(b.subject)+'</b><br>':'')+'<span class="dim">'+esc(short(b.batch,24))+' · from '+esc(b.from)+'</span></td><td>'+esc(ws.length>60?ws.slice(0,60)+'…':ws)+'<div class="dim">'+b.briefCount+' brief'+(b.briefCount===1?'':'s')+'</div></td><td>'+b.checkpointCount+'</td><td>'+b.finalCount+'</td><td>'+b.ackedFinals+'/'+b.finalCount+'</td><td>'+esc(ago(b.lastAt))+'</td></tr>';
+    }).join('')||'<tr><td colspan="6" class="dim">no briefs yet</td></tr>';
+    Array.prototype.forEach.call(document.querySelectorAll('[data-batch]'),function(r){r.onclick=function(){showBrief(r.getAttribute('data-batch'));};});
     try{
       var fr=await fetch('/api/fleet',{cache:'no-store'});
       var fl=await fr.json();
@@ -1337,6 +1413,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 +1425,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 +1495,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 +1615,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 +1726,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 +1826,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>`;
 }
@@ -1824,12 +1930,40 @@ export async function handleWebDashboardRoute(req, res, url, d) {
         id: m.id, from: m.from, at: m.at, subject: m.subject || "",
         head: String(m.body || "").slice(0, 160),
         replyTo: m.replyTo || "", batch: m.batch || "",
+        checkpoint: m.checkpoint === true,
         artifact: m.artifact || "", acked: known.has(m.id),
       }));
     res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
     res.end(JSON.stringify({ board: d.root, agent, items }));
     return true;
   }
+  if (req.method === "GET" && url.pathname === "/api/gather") {
+    // Open read like /api/board (the transcript is already visible piece
+    // by piece there); the dashboard twin of `gather --batch`: one brief
+    // thread — briefs, checkpoint timeline, final reports — oldest first.
+    const batch = String(url.searchParams.get("batch") || "").trim().slice(0, 200);
+    if (!batch) {
+      res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: "pass ?batch=<batch-id>" }));
+      return true;
+    }
+    const got = collectBatch(d, batch);
+    if (!got) {
+      res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: `unknown batch "${batch}"` }));
+      return true;
+    }
+    const known = ackedIdSet(d);
+    const tele = gatherTelemetry(got.items);
+    const items = got.items.map((m) => ({
+      id: m.id, from: m.from, to: m.to, at: m.at, subject: m.subject || "",
+      body: String(m.body || ""), replyTo: m.replyTo || "", batch: m.batch || "",
+      checkpoint: m.checkpoint === true, acked: known.has(m.id),
+    }));
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(JSON.stringify({ board: d.root, batch, briefs: got.briefs, replies: got.replies, telemetry: tele, items }));
+    return true;
+  }
   if (req.method === "POST" && url.pathname === "/api/ack") {
     // JSON-only like /api/kill (plain browser forms can't reach it),
     // token-checked like the CLI, no --verify over HTTP.
@@ -1889,12 +2023,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,107 @@
-# 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 sibling groups of the same spawn +
+members, their group channels, and the peer-DM norm. Groups from
+unrelated concurrent briefs are deliberately NOT enumerated — they
+collapse to a count (`N other groups exist on this board`), so
+cross-task rosters stay discoverable (`crewbus group list`) without
+becoming prompt noise or a misleading invitation. 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.
+