@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/hub/lib/collect.mjs

@@ -0,0 +1,342 @@
+// agents-hub lib/collect.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Builds everything the hub shows from what sessions leave on disk: Cursor transcripts (who exists, who started whom,
+// what each agent was asked), task channels (what happened, who has the ball) and the hub's own requests and events.
+// Tokens are an estimate (transcript bytes / 4): transcripts hold no usage, tool output or system prompts.
+import fs from 'node:fs';
+import path from 'node:path';
+import { managerChats } from '../core/ids.mjs';
+import { channelFiles, firstHeading, holds, parsePosts } from './channels.mjs';
+import { hasChatInbox, liveOf } from './chat.mjs';
+import { chatTitles } from './titles.mjs';
+import { buildAgents, buildDeliveries, streamView } from './deliveries.mjs';
+import { gitInfo, plannedCheckout, taskCheckout } from './git.mjs';
+import { personaFor, savePersonas } from './personas.mjs';
+import { HUB, readAccepted, readRequests } from './store.mjs';
+import { channelsOwned, pruneOwnCache, scanSessions, scanTranscripts, sessionTail, topSession } from './transcripts.mjs';
+
+const WORK = path.resolve(HUB, '..');
+const CHANNEL_ROOTS = ['AgentPulseApps', 'Google_Cloud'].map((d) => path.join(WORK, d));
+const ACTIVE_MS = 10 * 60e3;
+const IDLE_MS = 60 * 60e3;
+const ORPHAN_LOOKBACK_MS = 48 * 3600e3;
+/** A subagent file this small is the launch stub only; its real conversation was not saved, so its tokens are unknown. */
+const STUB_BYTES = 8 * 1024;
+const MANAGER = 'manager';
+/** Ids of the requests collect derives from channel posts. Other request facts (hub.mjs request, imports) are not its. */
+export const DERIVED_REQUEST_PREFIX = 'd-';
+const REQUEST_HINT = /\bPROMOTE\b|platform gap|needs? (?:a )?platform change|common script/i;
+
+/** The hub's Cursor hook fires on every tool call, so a chat it heard from this recently is running and gets messages at its next step. */
+const LIVE_MS = 3 * 60e3;
+
+function withLive(row, now) {
+  const chatInbox = hasChatInbox(row.id);
+  const live = chatInbox ? liveOf(row.id) : null;
+  row.reach = { ...row.reach, chatInbox, live };
+  if (!live || row.reach.state === 'finished' || live.at < row.reach.lastAt - LIVE_MS) return;
+  if (live.event === 'stop') row.reach.state = 'turn-ended';
+  else if (now - live.at < LIVE_MS) row.reach.state = 'connected';
+}
+
+const statusOf = (lastAt, now) => (now - lastAt < ACTIVE_MS ? 'active' : now - lastAt < IDLE_MS ? 'idle' : 'done');
+/**
+ * What header totals are counted from, so a window can filter one canonical pass (projections/graph.mjs). One entry per
+ * person, [kind 's' | 'a' | 'o', seenAt, lastAt, tokensEst], where seenAt is the later of lastAt and `seenAt`: a role
+ * that posted inside a window, holds the ball of a stream touched in it, or runs under the hub is in it even when its
+ * transcript is older. Message events collapse to [at, count].
+ */
+export function totalsBasis(people, events, seenAt = new Map()) {
+  const counts = new Map();
+  for (const e of events) counts.set(e.at, (counts.get(e.at) || 0) + 1);
+  const kind = (n) => (n.kind === 'session' ? 's' : n.kind === 'agent' ? 'a' : 'o');
+  return {
+    people: people.map((n) => [kind(n), Math.max(n.lastAt || 0, seenAt.get(n.id) || 0), n.lastAt || 0, n.tokensEst || 0]),
+    messages: [...counts].sort((a, b) => a[0] - b[0]),
+  };
+}
+
+const titleCase = (s) => s.toLowerCase().replace(/(^|\s)\w/g, (c) => c.toUpperCase());
+
+function recipients(role, roles) {
+  const others = roles.filter((r) => r !== role);
+  if (role.includes('CODER')) return others.filter((r) => r.includes('REVIEWER') || r.includes('AUDITOR'));
+  if (role.includes('REVIEWER') || role.includes('AUDITOR')) return others.filter((r) => r.includes('CODER'));
+  return others.filter((r) => !r.includes('AUDITOR'));
+}
+
+/**
+ * Each stream belongs to one session: the parent of its agents, else the most recent session (up to 48 h back) whose
+ * briefs or writes name it. Sessions found that way join the node list, since they are the streams' architects.
+ */
+function assignOwners(nodes, channels, index, now) {
+  const owner = new Map();
+  for (const c of channels) {
+    const parented = [...nodes.values()].find((n) => n.channelKey === c.key && n.parent && nodes.get(n.parent) && nodes.get(n.parent).kind === 'session');
+    if (parented) owner.set(c.key, parented.parent);
+  }
+  const missing = new Set(channels.filter((c) => !owner.has(c.key)).map((c) => c.key));
+  if (missing.size) {
+    for (const s of scanSessions(now - ORPHAN_LOOKBACK_MS, index).sort((a, b) => b.lastAt - a.lastAt)) {
+      if (!missing.size) break;
+      const top = topSession(s.id, index) || s;
+      for (const k of channelsOwned(s.file, index)) {
+        if (!missing.has(k)) continue;
+        missing.delete(k);
+        owner.set(k, top.id);
+        if (!nodes.has(top.id)) nodes.set(top.id, top);
+      }
+    }
+  }
+  pruneOwnCache(now - ORPHAN_LOOKBACK_MS);
+  for (const n of nodes.values()) if (n.kind === 'agent' && !n.parent && n.channelKey && owner.has(n.channelKey) && owner.get(n.channelKey) !== n.id) n.parent = owner.get(n.channelKey);
+  return owner;
+}
+
+/**
+ * Whoever holds a stream's ball must be on the map even if it has not posted inside the time window (a coder sitting
+ * on a failed review is exactly what you need to see): add it from its last post in the channel.
+ */
+function addBallHolders(nodes, streams, owner, now) {
+  for (const s of streams.values()) {
+    if (s.done || !s.ball || s.ball === 'YOU' || s.ball === 'ARCHITECT') continue;
+    if ([...nodes.values()].some((n) => n.channelKey === s.key && n.role && holds(n.role, s.ball))) continue;
+    const [role, post] = Object.entries(s.lastByRole).filter(([r]) => holds(r, s.ball)).sort((a, b) => b[1].at - a[1].at)[0] || [];
+    if (!role) continue;
+    const id = `${s.key}:${role}`;
+    nodes.set(id, { id, kind: 'agent', role, task: s.channel, channel: s.channel, channelKey: s.key, repo: s.repo, label: titleCase(role),
+      title: `${role} on ${s.channel} (seen only in its channel)`, parent: owner.get(s.key) || null, startedAt: post.at, lastAt: post.at, bytes: 0, tokensEst: null, status: statusOf(post.at, now), synthetic: true });
+  }
+}
+
+/**
+ * When each stream's ball holder was last on the map. A window shows the holder whenever the stream's channel changed
+ * inside it (addBallHolders), so in the canonical pass the holder counts as seen at the channel's last change.
+ */
+function ballHeldAt(nodes, streams, channels) {
+  const changed = new Map(channels.map((c) => [c.key, c.mtime]));
+  const held = new Map();
+  for (const s of streams.values()) {
+    if (s.done || !s.ball || s.ball === 'YOU' || s.ball === 'ARCHITECT') continue;
+    if (!Object.keys(s.lastByRole).some((r) => holds(r, s.ball))) continue;
+    let holder = null;
+    for (const n of nodes.values()) if (n.channelKey === s.key && n.role && holds(n.role, s.ball) && (!holder || n.lastAt > holder.lastAt)) holder = n;
+    if (holder) held.set(holder.id, Math.max(held.get(holder.id) || 0, changed.get(s.key) || 0));
+  }
+  return held;
+}
+
+/** Task titles from the briefs each owner session gave its subagents: for agents without their own transcript, and per stream. */
+function applyBriefs(nodes, channels, owner, index) {
+  const byKey = new Map();
+  for (const sid of new Set(owner.values())) {
+    const s = nodes.get(sid);
+    if (!s || !s.file) continue;
+    for (const [k, roles] of channelsOwned(s.file, index).briefs) byKey.set(k, roles);
+  }
+  const titles = new Map();
+  for (const c of channels) {
+    const roles = byKey.get(c.key);
+    c.title = streamTitle(c) || (roles && [...roles.values()].map((b) => b.title).find(Boolean)) || null;
+    titles.set(c.key, c.title);
+  }
+  for (const n of nodes.values()) {
+    if (n.kind !== 'agent' || n.taskTitle || !n.channelKey) continue;
+    const roles = byKey.get(n.channelKey);
+    const b = roles && (roles.get(n.role) || [...roles.values()].find((x) => n.role && x.role && (x.role.endsWith(n.role) || n.role.endsWith(x.role))));
+    n.taskTitle = (b && b.title) || titles.get(n.channelKey) || null;
+    if (b && (!n.task || n.synthetic)) n.task = b.code;
+  }
+}
+
+/** A stream's title: the heading of brief.md beside its channel, else of the spec its KICKOFF names. */
+function streamTitle(c) {
+  const dir = path.dirname(c.file);
+  const brief = firstHeading(path.join(dir, 'brief.md'));
+  if (brief) return brief;
+  const kickoff = c.posts.find((p) => /^KICKOFF/.test(p.type.toUpperCase()));
+  const spec = kickoff && kickoff.text.match(/(docs\/[A-Za-z0-9._/-]+\.md)/);
+  if (!spec || spec[1].split('/').includes('..')) return null;
+  const repoDir = path.resolve(dir, '..', '..');
+  return firstHeading(path.join(repoDir, spec[1]));
+}
+
+const postCache = new Map();
+/** A channel's posts, re-parsed only when the file changed. */
+function postsOf(c) {
+  let size = 0;
+  try { size = fs.statSync(c.file).size; } catch { return []; }
+  const hit = postCache.get(c.file);
+  if (hit && hit.mtime === c.mtime && hit.size === size) return hit.posts;
+  let posts = [];
+  try { posts = parsePosts(fs.readFileSync(c.file, 'utf8'), c.mtime); } catch { /* unreadable */ }
+  if (postCache.size > 2000) postCache.clear();
+  postCache.set(c.file, { mtime: c.mtime, size, posts });
+  return posts;
+}
+
+/** The whole picture for the last `hours`. */
+/** Hub-owned agents (runs): their sessions may have a Cursor transcript (relabel it) or none (Claude, other CLIs). */
+function adoptRuns(nodes, runs, since) {
+  for (const r of runs) {
+    if (r.state === 'stopped' && (r.lastAt || r.createdAt) < since) continue;
+    const prev = nodes.get(r.id);
+    const channel = r.stream ? r.stream.split('/').pop() : null;
+    nodes.set(r.id, {
+      ...(prev || { bytes: 0, tokensEst: null }),
+      id: r.id, kind: 'agent', role: r.role, parent: r.parent || MANAGER, channelKey: r.stream || null, channel, task: channel,
+      repo: path.basename(r.workspace), label: titleCase(r.role), title: r.name || `${r.role} (${r.driver}, hub-owned)`,
+      startedAt: (prev && prev.startedAt) || r.createdAt, lastAt: Math.max((prev && prev.lastAt) || 0, r.lastAt || r.createdAt),
+      hubRun: { driver: r.driver, state: r.state, turns: r.turns || 0, costUsd: r.costUsd || 0, lastError: r.lastError || null },
+    });
+  }
+}
+
+export function collect({ hours = 6, runs = [], aliases = [] } = {}) {
+  const now = Date.now();
+  const since = now - hours * 3600e3;
+  const channels = channelFiles(CHANNEL_ROOTS, since);
+  const index = new Map();
+  for (const c of channels) {
+    c.posts = postsOf(c);
+    if (!index.has(c.task)) index.set(c.task, []);
+    index.get(c.task).push(c.key);
+  }
+  const nodes = scanTranscripts(since, index);
+  adoptRuns(nodes, runs, since);
+  // The headless Hub Manager has a Cursor transcript too, but it is the single central manager node, not a user
+  // delivery. Any subagents it starts hang from that manager node.
+  let ownChats = new Set();
+  try { ownChats = managerChats(JSON.parse(fs.readFileSync(path.join(HUB, 'state', 'manager.json'), 'utf8'))); } catch { /* manager not configured */ }
+  for (const chat of ownChats) nodes.delete(chat);
+  for (const n of nodes.values()) if (ownChats.has(n.parent)) n.parent = MANAGER;
+  const owner = assignOwners(nodes, channels, index, now);
+  /** A stream run by a subagent belongs to the session at the top of its chain. */
+  const rootOf = (id) => { let n = nodes.get(id); for (let i = 0; n && n.kind === 'agent' && n.parent && i < 8; i++) n = nodes.get(n.parent); return n && n.kind === 'session' ? n.id : null; };
+  for (const [k, id] of owner) { const n = nodes.get(id); if (n && n.kind === 'agent') { const root = rootOf(id); if (root) owner.set(k, root); else owner.delete(k); } }
+  for (const n of nodes.values()) {
+    n.status = statusOf(n.lastAt, now);
+    n.tokensEst = n.parent && n.bytes < STUB_BYTES ? null : Math.round(n.bytes / 4);
+  }
+  for (const c of channels) {
+    c.checkout = gitInfo(path.resolve(path.dirname(c.file), '..', '..'));
+    const kickoff = c.posts.find((p) => /^KICKOFF/.test(p.type.toUpperCase()));
+    c.planned = kickoff ? plannedCheckout(kickoff.text) : null;
+    c.git = taskCheckout(c.checkout, c.planned);
+  }
+  const streams = new Map(channels.map((c) => [c.key, streamView(c, { aliases })]));
+  addBallHolders(nodes, streams, owner, now);
+  const seenAt = ballHeldAt(nodes, streams, channels);
+  for (const n of nodes.values()) if (n.hubRun && n.hubRun.state !== 'stopped') seenAt.set(n.id, now);
+
+  const events = [];
+  const linkCount = new Map();
+  const bump = (a, b, kind) => { const k = `${a}|${b}|${kind}`; linkCount.set(k, (linkCount.get(k) || 0) + 1); };
+  const byKeyRole = new Map();
+  for (const n of nodes.values()) if (n.channelKey && n.role) {
+    const k = `${n.channelKey}|${n.role}`;
+    const prev = byKeyRole.get(k);
+    if (!prev || prev.lastAt < n.lastAt) byKeyRole.set(k, n);
+  }
+  const derived = [];
+  const derivedIds = new Map();
+  for (const c of channels) {
+    const posts = c.posts.filter((p) => p.at >= since);
+    if (!posts.length) continue;
+    const roles = [...new Set(posts.map((p) => p.role))];
+    const architect = owner.get(c.key) || null;
+    const nodeFor = (role) => {
+      if (role === 'USER') return 'user';
+      const hit = byKeyRole.get(`${c.key}|${role}`);
+      if (hit) return hit.id;
+      if (role === 'ARCHITECT' && architect) return architect;
+      const id = `${c.key}:${role}`;
+      if (!nodes.has(id)) {
+        const mine = posts.filter((p) => p.role === role);
+        const last = mine[mine.length - 1].at;
+        nodes.set(id, { id, kind: 'agent', role, task: c.task, channel: c.task, channelKey: c.key, repo: c.repo, label: titleCase(role),
+          title: `${role} on ${c.task} (seen only in its channel)`, parent: architect, startedAt: mine[0].at, lastAt: last, bytes: 0, tokensEst: null, status: statusOf(last, now), synthetic: true });
+      }
+      return id;
+    };
+    for (const p of posts) {
+      const from = nodeFor(p.role);
+      seenAt.set(from, Math.max(seenAt.get(from) || 0, p.at));
+      for (const r of recipients(p.role, roles)) {
+        const to = nodeFor(r);
+        events.push({ at: p.at, from, to, type: p.type, text: p.text.slice(0, 300), channel: c.task });
+        bump(from, to, 'msg');
+      }
+      if (!REQUEST_HINT.test(p.head)) continue;
+      // Posts share a second often enough; each is its own request.
+      const base = `${DERIVED_REQUEST_PREFIX}${c.key}-${p.at}`;
+      const seq = derivedIds.get(base) || 0;
+      derivedIds.set(base, seq + 1);
+      derived.push({ id: seq ? `${base}-${seq}` : base, title: p.text.replace(/^[^—]*— ?/, '').slice(0, 120), kind: 'platform', from: [from], status: 'unfiled', at: p.at, channel: c.task });
+    }
+  }
+
+  const requests = [...readRequests().filter((r) => r.at >= since), ...derived];
+  for (const r of requests) for (const f of r.from) if (nodes.has(f)) bump(f, MANAGER, 'request');
+  nodes.set(MANAGER, { id: MANAGER, kind: 'manager', label: 'Manager', title: 'Owns shared changes: platform, common scripts, rules', status: 'active', startedAt: since, lastAt: now, tokensEst: null });
+
+  const links = [];
+  for (const n of nodes.values()) if (n.parent && nodes.has(n.parent)) links.push({ source: n.parent, target: n.id, kind: 'spawn', count: 1 });
+  for (const [k, count] of linkCount) {
+    const [source, target, kind] = k.split('|');
+    if (nodes.has(source) && nodes.has(target) && source !== target) links.push({ source, target, kind, count });
+  }
+  const sent = new Map();
+  const got = new Map();
+  for (const e of events) { sent.set(e.from, (sent.get(e.from) || 0) + 1); got.set(e.to, (got.get(e.to) || 0) + 1); }
+  events.sort((a, b) => a.at - b.at);
+
+  applyBriefs(nodes, channels, owner, index);
+  for (const c of channels) { const v = streams.get(c.key); if (v) v.title = c.title || null; }
+  for (const n of nodes.values()) {
+    if (n.kind !== 'agent' && !(n.kind === 'session' && !n.parent)) continue;
+    const p = personaFor(n.id, { role: n.kind === 'agent' ? n.role : 'ARCHITECT', channel: n.channelKey || null, now: Math.min(now, n.startedAt || now) });
+    n.persona = { name: p.name, first: p.first, username: p.username, seed: p.seed, personality: p.personality || null };
+  }
+  savePersonas();
+  const sessions = [...nodes.values()].filter((n) => n.kind === 'session' && !n.parent && n.file);
+  const kids = new Map();
+  for (const n of nodes.values()) if (n.parent && n.kind === 'agent') { if (!kids.has(n.parent)) kids.set(n.parent, []); kids.get(n.parent).push(n); }
+  const tails = new Map(sessions.map((s) => [s.id, sessionTail(s.file)]));
+  const deliveries = buildDeliveries({ sessions, kids, streams, owner, tails, acks: readAccepted(), now });
+  const names = chatTitles(deliveries.map((d) => d.id));
+  for (const d of deliveries) {
+    d.name = names.get(d.id) || null;
+    const session = nodes.get(d.id);
+    if (session) Object.assign(session, {
+      role: 'ARCHITECT', nodeType: 'delivery', chatTitle: d.name || d.title, label: d.name || d.title, promptTitle: d.title,
+      deliveryId: d.id, project: d.projects.join(', '),
+    });
+  }
+  const nodeList = [...nodes.values()];
+  const agentRows = buildAgents({ nodes: nodeList, streams, owner, deliveries, tails, now });
+  for (const row of agentRows) withLive(row, now);
+  const RUN_STATUS = { working: 'working', queued: 'working', idle: 'waiting', error: 'stuck', stopped: 'done' };
+  for (const row of agentRows) {
+    const n = nodes.get(row.id);
+    if (!n || !n.hubRun) continue;
+    row.hubRun = n.hubRun;
+    row.status = RUN_STATUS[n.hubRun.state] || row.status;
+    row.reach = { ...row.reach, state: n.hubRun.state === 'stopped' ? 'finished' : 'connected', chatInbox: n.hubRun.state !== 'stopped', hubRun: n.hubRun.driver };
+  }
+
+  const list = nodeList.map(({ file, bytes, ...n }) => ({ ...n, msgsOut: sent.get(n.id) || 0, msgsIn: got.get(n.id) || 0 }));
+  const people = list.filter((n) => n.kind !== 'manager');
+  return {
+    generatedAt: now, hours, deliveries, agents: agentRows,
+    totals: {
+      sessions: people.filter((n) => n.kind === 'session').length,
+      agents: people.filter((n) => n.kind === 'agent').length,
+      active: people.filter((n) => n.status === 'active').length,
+      messages: events.length,
+      tokensEst: people.reduce((s, n) => s + (n.tokensEst || 0), 0),
+      requests: requests.length,
+    },
+    totalsBasis: totalsBasis(people, events, seenAt),
+    nodes: list, links, events: events.slice(-400), requests: requests.sort((a, b) => b.at - a.at),
+  };
+}

package/src/hub/lib/deliveries.mjs

@@ -0,0 +1,222 @@
+// agents-hub lib/deliveries.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Deliveries and agent rows from analysed work streams. Pure: everything it needs is passed in, so it is tested
+// with fixtures. A delivery is one orchestrating session; its work streams are the channels it owns.
+import { STEPS, analyseStream, holds, movesWork, postStep } from './channels.mjs';
+import { closedReason, closedText, roleOutcome } from './closure.mjs';
+
+const APPS = ['agentforce-builder', 'agentforce-review', 'agent-studio', 'datacloud-builder', 'agentforce', 'ai-hub', 'insights', 'org-map'];
+const IDLE_MS = 10 * 60e3;
+export const STUCK_MS = 30 * 60e3;
+/** Pulse 1.1.2 (E4): a newest post stamped this far past the file's last write is future-dated on the Board. */
+const FUTURE_MS = 5 * 60e3;
+const REPLY_MAX_AGE_MS = 6 * 3600e3;
+const ASKS_REPLY = /\?\s*$|\b(should i|want me to|shall i|do you want|your call|let me know|which (one|option)|approve)\b/i;
+
+export function projectOf(repo) {
+  if (!repo) return null;
+  if (/^AgentforceVoice/.test(repo)) return 'platform';
+  const rest = repo.replace(/^agentpulse-/, '');
+  return APPS.find((a) => rest === a || rest.startsWith(`${a}-`)) || rest;
+}
+
+const clean = (s) => String(s || '').replace(/\s+/g, ' ').replace(/[*`#]/g, '').trim();
+const cut = (s, max) => { const t = clean(s); return t.length > max ? t.slice(0, max - 1) + '…' : t; };
+const firstSentence = (s, max = 200) => { const t = clean(s); const m = t.match(/^(.{20,}?[.?!])(\s|$)/); return cut(m ? m[1] : t, max); };
+const tailText = (s, max = 240) => { const t = clean(s); return t.length > max ? '…' + t.slice(-max + 1) : t; };
+const mins = (ms) => Math.max(1, Math.round(ms / 60e3));
+/** A post's substance: what follows the header's "TYPE #id —" prefix. */
+const detail = (text) => { const t = clean(text).replace(/^FINAL:? ?FAIL\b[\s:—-]*/i, ''); const i = t.indexOf(' — '); return i > 0 && i < 90 ? t.slice(i + 3) : t; };
+
+/** What the person holding the ball is doing, in words. */
+function ballText(a) {
+  if (a.done) return closedText(a.outcome);
+  if (a.ball === 'YOU') return 'Waiting for your decision';
+  if (a.failed) return a.failed.role === 'USER' ? 'You asked for changes; the coder is on it' : 'Final review failed; the coder is reworking it';
+  if (a.blockers.length) {
+    if (a.ball === 'CODER') return `Coder is fixing ${a.blockers.length} blocker${a.blockers.length > 1 ? 's' : ''}`;
+    if (a.ball === 'REVIEWER') return 'Waiting for the reviewer to verify the fix';
+    if (a.ball === 'AUDITOR') return 'Waiting for the auditor to verify the fix';
+    if (a.ball === 'ARCHITECT') return 'Deploy blocked; the architect is on it';
+  }
+  if (a.ball === 'ARCHITECT') {
+    if (a.question) return 'Coder asked the architect a question';
+    return a.step >= 6 ? 'Waiting for the architect to merge or release' : 'Waiting for the architect to deploy and post evidence';
+  }
+  if (a.ball === 'REVIEWER') return a.step >= 5 ? 'Waiting for the reviewer\u2019s final call' : 'Waiting for review';
+  if (a.ball === 'AUDITOR') return 'Waiting for the auditor';
+  if (a.ball === 'CODER') return a.step <= 3 ? 'Coder is building' : 'Coder is addressing review';
+  return 'Working';
+}
+
+/** A channel's posts → the summary the UI shows for one work stream. */
+export function streamView(c, { aliases = [] } = {}) {
+  const a = analyseStream(c.posts, { aliases });
+  const last = c.posts[c.posts.length - 1];
+  const moved = c.posts.filter(movesWork);
+  /** Positions are 1-based places in the channel: the order the hub compares by, since headers carry agents' clocks. */
+  const seqs = c.posts.map((p, i) => (movesWork(p) ? i + 1 : 0)).filter(Boolean);
+  const movedSeqByRole = {};
+  for (const i of seqs) movedSeqByRole[c.posts[i - 1].role] = i;
+  return {
+    key: c.key, channel: c.task, title: c.title || null, repo: c.repo, project: projectOf(c.repo), file: c.file,
+    git: c.git || null,
+    step: a.step, stepName: a.stepName, round: a.round, done: a.done, outcome: a.done ? a.outcome || 'passed' : null,
+    failed: a.failed ? firstSentence(detail(a.failed.text), 200) : null, failedBy: a.failed ? a.failed.role : null,
+    blockers: a.blockers.map((b) => ({ id: b.id, role: b.role, at: b.at, text: firstSentence(detail(b.text), 220) })),
+    needsUser: a.needsUser && { at: a.needsUser.at, text: a.needsUser.text, ref: a.needsUser.ids[0] || null },
+    openAsks: a.asks.length,
+    question: a.question && { at: a.question.at, text: firstSentence(a.question.text, 200) },
+    final: a.lastFinal && { at: a.lastFinal.at, text: cut(a.lastFinal.text, 160) },
+    evidence: a.lastEvidence && { at: a.lastEvidence.at, text: cut(detail(a.lastEvidence.text), 200) },
+    ball: a.ball, ballAt: a.ballAt, ballText: ballText(a), lastByRole: a.lastByRole,
+    lastAt: Math.max(c.mtime, last ? last.at : 0), lastPost: last && { role: last.role, type: last.type, text: cut(last.text, 200), at: last.at, writtenAt: c.mtime, ...(last.at - c.mtime > FUTURE_MS ? { futureDated: true } : {}) },
+    agentAt: moved.length ? moved[moved.length - 1].at : null, movedByRole: Object.fromEntries(moved.map((p) => [p.role, p.at])),
+    agentSeq: seqs.length ? seqs[seqs.length - 1] : 0, movedSeqByRole,
+    stepSeq: STEPS.map((_, i) => seqs.reduce((at, n) => (postStep(c.posts[n - 1]) >= i ? n : at), 0)),
+  };
+}
+
+/**
+ * sessions: top-level session nodes; kids: Map session id → its agent nodes; streams: Map key → streamView;
+ * owner: Map stream key → session id; tails: Map session id → sessionTail(); acks: Map delivery id → when you accepted
+ * its result.
+ */
+export function buildDeliveries({ sessions, kids, streams, owner, tails, acks = new Map(), now }) {
+  const out = [];
+  for (const s of sessions) {
+    const agents = kids.get(s.id) || [];
+    const mine = [...owner].filter(([, sid]) => sid === s.id).map(([k]) => streams.get(k)).filter(Boolean).sort((a, b) => b.lastAt - a.lastAt);
+    const tail = tails.get(s.id) || { state: 'unknown', lastText: '' };
+    const active = agents.filter((a) => now - a.lastAt < IDLE_MS).length;
+    const lastAt = Math.max(s.lastAt, ...mine.map((x) => x.lastAt), ...agents.map((a) => a.lastAt));
+    const open = mine.filter((x) => !x.done);
+    const stepCounts = STEPS.map((_, i) => open.filter((x) => x.step === i).length);
+    const step = open.length ? stepCounts.lastIndexOf(Math.max(...stepCounts)) : mine.length ? STEPS.length - 1 : null;
+    const idle = now - lastAt > IDLE_MS && !active;
+    const titles = [...new Set([...mine.map((x) => x.title), ...agents.map((a) => a.taskTitle)].filter(Boolean))];
+
+    const lastFinalAt = Math.max(0, ...mine.map((x) => (x.final ? x.final.at : 0)));
+    const accepted = (acks.get(s.id) || 0) >= lastFinalAt && lastFinalAt > 0;
+    /** When the holder of a stream's ball last did anything: its agents, or this session when the architect holds it. */
+    const holderLast = (x) => (x.ball === 'ARCHITECT' ? s.lastAt : Math.max(0, ...agents.filter((a) => a.channelKey === x.key && holds(a.role, x.ball)).map((a) => a.lastAt)));
+    const quietFor = (x) => now - Math.max(x.ballAt || x.lastAt, holderLast(x));
+
+    let ask = null;
+    const nu = open.find((x) => x.needsUser);
+    if (tail.state === 'asking') ask = { kind: 'question', label: 'Question for you', decide: tail.question.prompt, options: tail.question.options, more: tail.question.more, then: 'The session continues as soon as you answer in its Cursor chat.' };
+    else if (nu) ask = { kind: 'decision', label: 'Design decision', decide: firstSentence(nu.needsUser.text, 260), full: clean(nu.needsUser.text), stream: nu.channel, key: nu.key, ref: nu.needsUser.ref, at: nu.needsUser.at, more: nu.openAsks - 1, then: 'The architect applies your decision and the coder continues.' };
+    else if (mine.length && !open.length && idle && !accepted && mine.every((x) => (x.outcome || 'passed') === 'passed')) {
+      ask = { kind: 'result', label: 'Result ready', decide: `All ${mine.length} work stream${mine.length > 1 ? 's' : ''} passed final review. Check the proof, then accept.`, then: 'Release or merge is yours: agents never push.',
+        proof: mine.flatMap((x) => [x.final && `${x.title || x.channel}: ${x.final.text}`, x.evidence && `Evidence: ${x.evidence.text}`]).filter(Boolean).slice(0, 12) };
+    } else if (tail.state === 'turn-ended' && idle && now - lastAt < REPLY_MAX_AGE_MS && ASKS_REPLY.test(tail.lastText.slice(-400))) ask = { kind: 'reply', label: 'Waiting for your reply', decide: tailText(tail.lastText), then: 'The session picks up from your reply.' };
+
+    const failed = open.find((x) => x.failed && x.failedBy !== 'USER');
+    const blocked = open.find((x) => x.blockers.length);
+    const stuck = open.filter((x) => x.ball && x.ball !== 'YOU' && quietFor(x) > STUCK_MS).sort((a, b) => quietFor(b) - quietFor(a))[0];
+    let status; let reason;
+    if (ask) { status = 'needs-you'; reason = ask.label; }
+    else if (failed) { status = 'blocked'; reason = `${failed.channel}: final review failed. ${failed.failed}`; }
+    else if (blocked) { const b = blocked.blockers[0]; status = 'blocked'; reason = `${blocked.channel}: blocker #${b.id} from the ${b.role.toLowerCase()}: ${b.text}`; }
+    else if (mine.length && !open.length) { status = 'done'; reason = accepted ? 'Accepted' : closedReason(mine.map((x) => x.outcome)); }
+    else if (!mine.length && tail.state === 'turn-ended' && idle) { status = 'done'; reason = 'Answered'; }
+    else if (stuck) { status = 'stuck'; reason = `${stuck.channel}: ${stuck.ballText.toLowerCase()}, nothing for ${mins(quietFor(stuck))} min`; }
+    else if (open.length) { const x = open[0]; status = 'on-track'; reason = `${x.channel}: ${x.ballText.toLowerCase()}`; }
+    else { status = 'on-track'; reason = active ? `${active} agent${active > 1 ? 's' : ''} working` : 'Working'; }
+
+    out.push({
+      id: s.id, title: firstSentence(s.title, 110), subtitle: titles.slice(0, 3).join(' · '), projects: [...new Set(mine.map((x) => x.project).filter(Boolean))],
+      streams: mine.map(({ lastByRole, movedByRole, ...x }) => x), step, stepName: step == null ? null : STEPS[step], stepCounts, done: mine.length - open.length,
+      status, reason, ask, agents: agents.length, active, tokens: [s, ...agents].reduce((n, a) => n + (a.tokensEst || 0), 0),
+      startedAt: s.startedAt, lastAt, sessionState: tail.state,
+    });
+  }
+  const rank = { 'needs-you': 0, blocked: 1, stuck: 2, 'on-track': 3, done: 4 };
+  return out.sort((a, b) => rank[a.status] - rank[b.status] || b.lastAt - a.lastAt);
+}
+
+/** One row per agent: its task, what it last did, who it waits on, and whether it is working, waiting, stuck or done. */
+export function buildAgents({ nodes, streams, owner, deliveries, tails = new Map(), now }) {
+  const byDelivery = new Map(deliveries.map((d) => [d.id, d]));
+  const rows = [];
+  for (const n of nodes) {
+    if (n.kind !== 'agent') continue;
+    const s = n.channelKey && streams.get(n.channelKey);
+    const deliveryId = (s && owner.get(s.key)) || n.parent || null;
+    const d = deliveryId && byDelivery.get(deliveryId);
+    const byRole = (m) => s && n.role && (m[n.role] || Object.entries(m).find(([r]) => r && (r.endsWith(n.role) || n.role.endsWith(r)))?.[1]);
+    const mine = byRole(s ? s.lastByRole : {});
+    const lastAct = Math.max(n.lastAt, mine ? mine.at : 0);
+    let status; let waitingOn = null;
+    if (!s) status = now - n.lastAt < IDLE_MS ? 'working' : 'done';
+    else if (s.done || roleOutcome(mine)) status = 'done';
+    else if (holds(n.role, s.ball)) status = now - Math.max(s.ballAt || 0, lastAct) > STUCK_MS ? 'stuck' : 'working';
+    else if (s.ball) { status = 'waiting'; waitingOn = s.ball; }
+    else status = now - lastAct < IDLE_MS ? 'working' : 'idle';
+    rows.push({
+      id: n.id, role: n.role, label: n.label, task: n.taskTitle || n.task || n.channel || null, code: n.task || null,
+      deliveryId, deliveryTitle: d ? d.title : null, streamKey: s ? s.key : null, channel: n.channel, project: s ? s.project : projectOf(n.repo),
+      status, waitingOn, doing: mine ? { type: mine.type, text: cut(mine.text, 180), at: mine.at } : null, lastAt: lastAct, startedAt: n.startedAt,
+      tokensEst: n.tokensEst, seenOnlyInChannel: !!n.synthetic, persona: n.persona || null, parentId: n.parent || null, movedAt: byRole(s ? s.movedByRole : {}) || null, movedSeq: byRole(s ? s.movedSeqByRole : {}) || 0,
+      reach: reachOf(s ? { key: s.key, channel: s.task } : null, n.lastAt, tails.get(n.id), status === 'done', now),
+    });
+  }
+  for (const d of deliveries) {
+    const s = nodes.find((n) => n.id === d.id);
+    if (s) rows.push(architectRow(s, d, tails.get(s.id), now));
+  }
+  const rank = { stuck: 0, working: 1, waiting: 2, idle: 3, done: 4 };
+  return rows.sort((a, b) => rank[a.status] - rank[b.status] || b.lastAt - a.lastAt);
+}
+
+/**
+ * Whether a message from you can reach an agent. A Cursor chat cannot be pushed into from outside: it only reads its
+ * channel during its own turn. So a message lands in the channel it reads, and is heard only while the session runs.
+ */
+function reachOf(inbox, lastAt, tail, finished, now) {
+  const state = finished ? 'finished' : !inbox ? 'no-inbox' : tail && tail.state === 'turn-ended' ? 'turn-ended'
+    : tail && tail.state === 'asking' ? 'asking' : now - lastAt < IDLE_MS ? 'running' : 'quiet';
+  return { streamKey: inbox ? inbox.key : null, channel: inbox ? inbox.channel : null, state, lastAt };
+}
+
+/**
+ * A session with no work streams yet: still a live Cursor chat you can message. Its state is its chat's, never
+ * "finished" — typing in it (or a message at its next turn) carries on.
+ */
+function sessionRow(s, d, tail, now, awake) {
+  const asking = tail && tail.state === 'asking';
+  const working = tail && tail.state === 'working' && awake;
+  return {
+    id: s.id, role: 'ARCHITECT', label: 'Architect', isArchitect: true, task: d.subtitle || d.title, code: null, deliveryId: d.id, deliveryTitle: d.title,
+    streamKey: null, channel: null, project: d.projects.join(', '), status: asking ? 'waiting' : working ? 'working' : 'idle', waitingOn: asking ? 'YOU' : null,
+    doing: { type: asking ? 'Question for you' : 'Chat', text: d.reason, at: s.lastAt },
+    lastAt: s.lastAt, startedAt: s.startedAt, tokensEst: s.tokensEst, seenOnlyInChannel: false, persona: s.persona || null,
+    reach: { ...reachOf({ key: null, channel: null }, s.lastAt, tail, false, now), chat: d.title, workspace: d.projects[0] || null },
+  };
+}
+
+/** The orchestrating session as the ARCHITECT of its streams: what it owes (deploy, evidence, answers) and whether it is on it. */
+function architectRow(s, d, tail, now) {
+  const open = d.streams.filter((x) => !x.done);
+  const owed = open.filter((x) => x.ball === 'ARCHITECT');
+  const awake = now - s.lastAt < IDLE_MS;
+  if (!d.streams.length) return sessionRow(s, d, tail, now, awake);
+  let status; let waitingOn = null;
+  if (!open.length) status = 'done';
+  else if (owed.length) status = awake || now - Math.min(...owed.map((x) => x.ballAt || x.lastAt)) < STUCK_MS ? 'working' : 'stuck';
+  else {
+    status = 'waiting';
+    const balls = open.map((x) => x.ball).filter(Boolean);
+    waitingOn = balls.sort((a, b) => balls.filter((x) => x === b).length - balls.filter((x) => x === a).length)[0] || null;
+  }
+  const inbox = owed[0] || open.slice().sort((a, b) => b.lastAt - a.lastAt)[0] || null;
+  const owes = [...new Set(owed.map((x) => x.ballText.replace(/^Waiting for the architect to /, '').replace(/^Coder asked the architect a question$/, 'answer a question')))];
+  return {
+    id: s.id, role: 'ARCHITECT', label: 'Architect', isArchitect: true, task: d.subtitle || d.title, code: null, deliveryId: d.id, deliveryTitle: d.title,
+    streamKey: null, channel: null, project: d.projects.join(', '), status, waitingOn,
+    doing: owed.length ? { type: `Owes ${owed.length}`, text: `${owed.map((x) => x.channel).join(', ')}: ${owes.join('; ')}`, at: Math.max(...owed.map((x) => x.ballAt || x.lastAt)) }
+      : { type: 'Coordinating', text: `${open.length} open stream${open.length === 1 ? '' : 's'}`, at: s.lastAt },
+    lastAt: s.lastAt, startedAt: s.startedAt, tokensEst: s.tokensEst, seenOnlyInChannel: false, persona: s.persona || null,
+    movedAt: Math.max(0, ...d.streams.map((x) => x.agentAt || 0)) || null,
+    reach: { ...reachOf(inbox, s.lastAt, tail, !open.length, now), chat: d.title, workspace: d.projects[0] || null },
+  };
+}