@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

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 },
+  };
+}

package/src/hub/lib/git.mjs

@@ -0,0 +1,93 @@
+// agents-hub lib/git.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Which branch a checkout is on, and whether it is a worktree of another repo, read from git's own files (no git
+// process): `<dir>/.git` is a directory for a main checkout, or a file `gitdir: <main>/.git/worktrees/<name>` for a
+// worktree. Cached by the HEAD file's mtime.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const cache = new Map();
+const readSmall = (file) => { try { return fs.readFileSync(file, 'utf8').slice(0, 4096).trim(); } catch { return null; } };
+
+/** { path, branch, sha, worktree, mainRepo } for a checkout directory, or null when it is not a git checkout. */
+export function gitInfo(dir) {
+  let gitDir = null;
+  let worktree = false;
+  try {
+    const st = fs.lstatSync(path.join(dir, '.git'));
+    if (st.isDirectory()) gitDir = path.join(dir, '.git');
+    else if (st.isFile()) {
+      const m = (readSmall(path.join(dir, '.git')) || '').match(/^gitdir:\s*(.+)$/m);
+      if (m) { gitDir = path.resolve(dir, m[1].trim()); worktree = true; }
+    }
+  } catch { return null; }
+  if (!gitDir) return null;
+  const headFile = path.join(gitDir, 'HEAD');
+  let mtime = 0;
+  try { mtime = fs.statSync(headFile).mtimeMs; } catch { return null; }
+  const hit = cache.get(dir);
+  if (hit && hit.mtime === mtime && hit.gitDir === gitDir) return hit.info;
+  const head = readSmall(headFile) || '';
+  const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+  const common = worktree ? readSmall(path.join(gitDir, 'commondir')) : null;
+  const mainGit = worktree ? path.resolve(gitDir, common || '../..') : gitDir;
+  const info = {
+    path: dir,
+    branch: ref ? ref[1] : null,
+    sha: ref ? null : (head.match(/^[0-9a-f]{7,40}$/) || [])[0]?.slice(0, 10) || null,
+    worktree,
+    mainRepo: worktree ? path.dirname(mainGit) : null,
+  };
+  if (cache.size > 500) cache.clear();
+  cache.set(dir, { mtime, gitDir, info });
+  return info;
+}
+
+function branchExists(mainGit, branch) {
+  if (fs.existsSync(path.join(mainGit, 'refs', 'heads', ...branch.split('/')))) return true;
+  return (readSmallBig(path.join(mainGit, 'packed-refs')) || '').includes(` refs/heads/${branch}\n`);
+}
+function readSmallBig(file) { try { return `${fs.readFileSync(file, 'utf8').slice(0, 2e6)}\n`; } catch { return null; } }
+
+/** Where a branch is checked out: the main checkout or one of its worktrees (from `.git/worktrees/<n>/{HEAD,gitdir}`). */
+function checkedOutAt(mainGit, branch) {
+  const want = `ref: refs/heads/${branch}`;
+  if (readSmall(path.join(mainGit, 'HEAD')) === want) return path.dirname(mainGit);
+  let names = [];
+  try { names = fs.readdirSync(path.join(mainGit, 'worktrees')); } catch { return null; }
+  for (const n of names) {
+    if (readSmall(path.join(mainGit, 'worktrees', n, 'HEAD')) !== want) continue;
+    const gitFile = readSmall(path.join(mainGit, 'worktrees', n, 'gitdir'));
+    if (gitFile) return path.dirname(gitFile);
+  }
+  return null;
+}
+
+/**
+ * A task's branch and worktree: the branch its KICKOFF named (else the one its channel's checkout is on), where that
+ * branch is checked out now, and whether the branch still exists.
+ */
+export function taskCheckout(checkout, planned) {
+  if (!checkout) return null;
+  const branch = (planned && planned.branch) || checkout.branch;
+  if (!branch) return { branch: null, sha: checkout.sha, worktreePath: checkout.path, isWorktree: checkout.worktree, mainRepo: checkout.mainRepo, channelCheckout: checkout.path, exists: null, here: true };
+  const mainGit = path.join(checkout.mainRepo || checkout.path, '.git');
+  const at = checkout.branch === branch ? checkout.path : checkedOutAt(mainGit, branch);
+  return {
+    branch,
+    worktreePath: at,
+    isWorktree: !!at && at !== (checkout.mainRepo || (checkout.worktree ? null : checkout.path)),
+    mainRepo: checkout.mainRepo || checkout.path,
+    channelCheckout: checkout.path,
+    channelBranch: checkout.branch,
+    exists: branchExists(mainGit, branch),
+    here: checkout.branch === branch,
+  };
+}
+
+/** The branch and worktree a KICKOFF post asked for ("Worktree <path>, branch <name>"). */
+export function plannedCheckout(text) {
+  const t = String(text || '');
+  const branch = (t.match(/\bbranch\s+`?([A-Za-z0-9._/-]+?)`?(?=[\s,.;)]|$)/i) || [])[1] || null;
+  const wt = (t.match(/\bworktree\s+`?([^\s,`]+)`?/i) || [])[1] || null;
+  return branch || wt ? { branch, worktree: wt ? wt.replace(/[).,]+$/, '') : null } : null;
+}

package/src/hub/lib/me.mjs

@@ -0,0 +1,123 @@
+// agents-hub lib/me.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Who "@you" is: the AgentPulse CLI's signed-in user. The CLI config holds no name, so the server asks the platform's
+// OIDC userinfo with the CLI's access token (as `agentpulse login` does) and keeps the answer in memory. The browser
+// only ever gets { name, handle, aliases }; the token goes only to the profile's own platform and is never logged.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { USER_ALIAS } from './channels.mjs';
+
+export const NOBODY = Object.freeze({ name: 'You', handle: null, aliases: Object.freeze([]) });
+/** Why the name is "You". Only these words are ever logged or kept, never an error message or a header. */
+export const REASONS = Object.freeze(['no-config', 'unauthorized', 'timeout', 'network', 'blank']);
+const TIMEOUT_MS = 3000;
+const FRESH_MS = 3600e3;
+const RETRY_MS = 5 * 60e3;
+const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+export const cliConfigPath = (env = process.env, home = os.homedir()) => path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'agentpulse', 'config.json');
+
+/** The CLI's active profile: its default, else its only one. */
+export function activeProfile(cfg) {
+  const profiles = (cfg && typeof cfg.profiles === 'object' && cfg.profiles) || {};
+  if (cfg && cfg.defaultProfile && profiles[cfg.defaultProfile]) return profiles[cfg.defaultProfile];
+  const names = Object.keys(profiles);
+  return names.length === 1 ? profiles[names[0]] : null;
+}
+
+/** The profile's platform origin, when the bearer may go there: https, or http on this machine. */
+export function platformOrigin(baseUrl) {
+  let u;
+  try { u = new URL(String(baseUrl)); } catch { return null; }
+  return u.protocol === 'https:' || (u.protocol === 'http:' && LOCAL.has(u.hostname)) ? u.origin : null;
+}
+
+const tidy = (s) => (typeof s === 'string' ? s.replace(/\s+/g, ' ').trim().slice(0, 60) : '');
+const localPart = (s) => tidy(s).split('@')[0];
+
+/**
+ * OIDC claims or a profile → { name, handle, aliases }: "First Last", else `name`, else the username; NOBODY when blank.
+ * Aliases are the handle and the name without spaces.
+ */
+export function identityOf(u) {
+  if (!u || typeof u !== 'object') return NOBODY;
+  const first = tidy(u.given_name || u.firstName || u.first_name);
+  const last = tidy(u.family_name || u.lastName || u.last_name);
+  const username = localPart(u.preferred_username || u.username || u.email);
+  const name = tidy([first, last].filter(Boolean).join(' ')) || tidy(u.name) || username;
+  if (!name) return NOBODY;
+  const handle = USER_ALIAS.test(username) ? username : null;
+  const aliases = [...new Set([handle, name.replace(/\s+/g, '')]
+    .filter((a) => a && USER_ALIAS.test(a) && !/^(you|user)$/i.test(a)).map((a) => a.toLowerCase()))];
+  return { name, handle, aliases };
+}
+
+/** The aliases no agent persona has: when the user's handle is also an agent's username, "@" it means the agent. */
+export const aliasesFor = (me, taken) => me.aliases.filter((a) => !taken.has(a.toLowerCase()));
+
+async function lookup(configPath, fetchImpl) {
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { return { reason: 'no-config' }; }
+  const profile = activeProfile(cfg);
+  if (!profile) return { reason: 'no-config' };
+  const own = identityOf(profile);
+  if (own !== NOBODY) return { me: own };
+  const origin = platformOrigin(profile.baseUrl);
+  if (!origin || typeof profile.accessToken !== 'string' || !profile.accessToken) return { reason: 'no-config' };
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  try {
+    const r = await fetchImpl(`${origin}/api/oauth/userinfo`, {
+      headers: { authorization: `Bearer ${profile.accessToken}`, accept: 'application/json' }, redirect: 'error', signal: ctl.signal,
+    });
+    if (r.status === 401 || r.status === 403) return { reason: 'unauthorized' };
+    if (!r.ok) return { reason: 'network' };
+    const got = identityOf(await r.json().catch(() => null));
+    return got === NOBODY ? { reason: 'blank' } : { me: got };
+  } catch {
+    return { reason: ctl.signal.aborted ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The CLI user, resolved in the background: `current()` never waits, and starts a lookup when the answer is stale (hourly,
+ * or every few minutes while it is still "You"). A failed lookup keeps the last good answer; `listen(fn)` hears changes,
+ * and `reason()` says why the name is "You".
+ */
+export function cliIdentity({ configPath = cliConfigPath(), fetchImpl = globalThis.fetch, now = Date.now, log = console.error } = {}) {
+  let me = NOBODY;
+  let why = null;
+  let checkedAt = -Infinity;
+  let running = null;
+  const listeners = new Set();
+  function refresh() {
+    if (running) return running;
+    checkedAt = now();
+    running = lookup(configPath, fetchImpl).then((got) => {
+      running = null;
+      if (got.reason) {
+        if (me === NOBODY && got.reason !== why) log(`@you shows "You": the CLI user could not be read (${got.reason})`);
+        why = got.reason;
+      } else {
+        why = null;
+        if (got.me.name !== me.name || got.me.aliases.join('|') !== me.aliases.join('|')) {
+          me = got.me;
+          for (const fn of listeners) fn(me);
+        }
+      }
+      return me;
+    });
+    return running;
+  }
+  return {
+    current() {
+      if (now() - checkedAt >= (me === NOBODY ? RETRY_MS : FRESH_MS)) refresh();
+      return me;
+    },
+    refresh,
+    reason: () => why,
+    listen(fn) { listeners.add(fn); },
+  };
+}

package/src/hub/lib/personas.mjs

@@ -0,0 +1,143 @@
+// agents-hub lib/personas.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Every agent gets a persona the first time the hub sees it: a first name, a surname, a username that is never reused,
+// and a seed for its illustrated face. The pairing is stored, so an agent keeps its identity for good.
+import fs from 'node:fs';
+import path from 'node:path';
+import { HUB } from './store.mjs';
+
+const FILE = path.join(HUB, 'state', 'personas.json');
+const RECENT_MS = 7 * 24 * 3600e3;
+const FIRST = [
+  'Maya', 'Arjun', 'Lena', 'Kofi', 'Sofia', 'Ravi', 'Noor', 'Mateo', 'Aiko', 'Elias', 'Priya', 'Tomas', 'Zara', 'Kenji', 'Amara', 'Luca',
+  'Ines', 'Dev', 'Hana', 'Omar', 'Clara', 'Jin', 'Asha', 'Felix', 'Leila', 'Nikhil', 'Mira', 'Diego', 'Yara', 'Sami', 'Ingrid', 'Tariq',
+  'Nora', 'Kai', 'Ananya', 'Bruno', 'Selin', 'Ade', 'Freya', 'Hugo', 'Meera', 'Rafael', 'Suki', 'Idris', 'Lina', 'Oskar', 'Tara', 'Malik',
+  'Esme', 'Rohan', 'Ayla', 'Theo', 'Kavya', 'Pablo', 'Rin', 'Yusuf', 'Alma', 'Ishaan', 'Greta', 'Emeka', 'Lea', 'Vikram', 'Saoirse', 'Ren',
+];
+const LAST = [
+  'Okafor', 'Sharma', 'Lindqvist', 'Mensah', 'Moreno', 'Iyer', 'Haddad', 'Silva', 'Tanaka', 'Novak', 'Reddy', 'Kowalski', 'Ahmed', 'Sato',
+  'Adeyemi', 'Rossi', 'Costa', 'Patel', 'Kim', 'Farouk', 'Weber', 'Chen', 'Nair', 'Fischer', 'Rahimi', 'Menon', 'Aydin', 'Garcia', 'Nkosi',
+  'Hassan', 'Berg', 'Qureshi', 'Larsen', 'Mori', 'Kapoor', 'Duarte', 'Yilmaz', 'Balogun', 'Olsen', 'Laurent', 'Pillai', 'Ortega', 'Ito',
+  'Abara', 'Vidal', 'Lund', 'Desai', 'Karimi', 'Brandt', 'Rao', 'Demir', 'Herrera', 'Watanabe', 'Eze', 'Nyberg', 'Joshi', 'Santos', 'Park',
+];
+
+/**
+ * A personality shapes how an agent talks to you in the hub: temperament, how it writes, and the emoji it reaches for.
+ * It is tone only. The role's duties are restated next to it every time, so a reviewer stays exacting and a coder
+ * stays precise, whatever its temperament.
+ */
+const TEMPERAMENT = ['warm and encouraging', 'dry and witty', 'calm and methodical', 'upbeat and energetic', 'thoughtful and curious',
+  'direct and no-nonsense', 'playful but sharp', 'quietly confident', 'friendly and plain-spoken', 'meticulous and a little wry'];
+const VOICE = ['writes short sentences and gets to the point', 'explains the why in one line', 'likes a quick checklist', 'asks one sharp question back when something is unclear',
+  'sums up first, then adds a light remark', 'speaks plainly, like a colleague at the next desk', 'leads with the answer and keeps the detail for when you ask'];
+const EMOJI_SETS = [['👍', '✅', '🚀'], ['🙂', '🙌', '✨'], ['👀', '🤔', '📝'], ['🔥', '💪', '🎉'], ['✅', '🧪', '🔍'], ['😄', '🎉', '☕'], ['👌', '🛠️', '📌'], ['🙏', '💡', '🌱']];
+const EMOJI_HABIT = ['rarely uses emoji', 'uses an emoji now and then', 'often answers with just an emoji when no words are needed'];
+const ROLE_DUTY = {
+  CODER: 'the coder: precise about what you built, tested and committed, and you never claim a check you did not run',
+  REVIEWER: 'the reviewer: exacting and honest; personality never softens a finding, a FAIL or a missing check',
+  ARCHITECT: 'the architect: you own the plan, the deploys and the evidence, and you keep every stream to its gates',
+  AUDITOR: 'the platform auditor: strict about alignment with the platform, and you flag drift plainly',
+  MANAGER: 'the hub manager: you coordinate across deliveries, deduplicate shared work and preserve every specialist role and gate',
+};
+
+function personalityFor(id) {
+  return {
+    temperament: TEMPERAMENT[hash(`temper:${id}`) % TEMPERAMENT.length],
+    voice: VOICE[hash(`voice:${id}`) % VOICE.length],
+    emoji: EMOJI_SETS[hash(`emoji:${id}`) % EMOJI_SETS.length],
+    habit: EMOJI_HABIT[hash(`habit:${id}`) % EMOJI_HABIT.length],
+  };
+}
+
+/** How an agent should sound when it answers you in the hub, with its role's duties restated so tone never changes the work. */
+export function voiceFor(id, role) {
+  let p = null;
+  try { p = (JSON.parse(fs.readFileSync(FILE, 'utf8')) || {})[id] || null; } catch { p = null; }
+  if (!p) return null;
+  const k = p.personality || personalityFor(id);
+  const r = String(role || p.role || '').toUpperCase().replace(/[^A-Z]/g, '');
+  const duty = ROLE_DUTY[r] || `the ${r ? r.toLowerCase() : 'agent'} on this task, doing that job exactly as before`;
+  return `In the hub you are ${p.name} (@${p.username}). Personality: ${k.temperament}; ${k.voice}; ${k.habit} (favourites: ${k.emoji.join(' ')}). `
+    + 'Answer like a human teammate with that personality: words, an emoji reaction, or both, whatever a person like you would send. '
+    + `It is tone only. You are still ${duty}. It changes nothing in your work or your standards. `
+    + 'Whatever the tone, keep the structure readable: a clear first sentence, short paragraphs, bullets, code blocks and tables where they help.';
+}
+
+let cache = null;
+let dirty = false;
+
+function hash(s) {
+  let x = 2166136261;
+  for (let i = 0; i < s.length; i++) { x ^= s.charCodeAt(i); x = Math.imul(x, 16777619); }
+  return x >>> 0;
+}
+const slug = (s) => s.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '');
+
+/** A username nobody has had: first.last, then first.last2, first.last3… */
+function uniqueUsername(first, last, all) {
+  const used = new Set(Object.values(all).map((p) => p.username).filter(Boolean));
+  const base = `${slug(first)}.${slug(last)}`;
+  if (!used.has(base)) return base;
+  let n = 2;
+  while (used.has(`${base}${n}`)) n++;
+  return `${base}${n}`;
+}
+
+/** Older personas had a first name only: give them a surname and a username, keeping name and face. */
+function upgrade(all) {
+  for (const [id, p] of Object.entries(all)) {
+    if (p && !p.personality) { p.personality = personalityFor(id); dirty = true; }
+    if (!p || p.username) continue;
+    const first = String(p.name || FIRST[hash(id) % FIRST.length]).split(' ')[0];
+    const last = LAST[hash(`last:${id}`) % LAST.length];
+    Object.assign(p, { first, last, name: `${first} ${last}`, username: uniqueUsername(first, last, all) });
+    dirty = true;
+  }
+}
+
+function load() {
+  if (cache) return cache;
+  try { cache = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { cache = {}; }
+  upgrade(cache);
+  return cache;
+}
+
+/** The persona of an agent id, creating it on first sight. First names are not reused among recent agents. */
+export function personaFor(id, { role = null, channel = null, now = Date.now() } = {}) {
+  const all = load();
+  if (all[id]) return all[id];
+  const recent = new Set(Object.values(all).filter((p) => now - p.createdAt < RECENT_MS).map((p) => p.first));
+  const start = hash(id) % FIRST.length;
+  let first = FIRST[start];
+  for (let i = 0; i < FIRST.length; i++) if (!recent.has(FIRST[(start + i) % FIRST.length])) { first = FIRST[(start + i) % FIRST.length]; break; }
+  const last = LAST[hash(`last:${id}`) % LAST.length];
+  all[id] = { first, last, name: `${first} ${last}`, username: uniqueUsername(first, last, all), seed: hash(`face:${id}`), role, channel, createdAt: now, personality: personalityFor(id) };
+  dirty = true;
+  return all[id];
+}
+
+/** Write new or upgraded personas to disk (once per pass). */
+export function savePersonas() {
+  if (!dirty || !cache) return;
+  fs.writeFileSync(FILE, JSON.stringify(cache, null, 2));
+  dirty = false;
+}
+
+let usernames = { mtime: null, set: new Set() };
+/** Every username an agent persona has had, re-read when the file changes (the collector writes it in its own thread). */
+export function personaUsernames() {
+  let mtime;
+  try { mtime = fs.statSync(FILE).mtimeMs; } catch { return new Set(); }
+  if (mtime !== usernames.mtime) {
+    let all = {};
+    try { all = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { /* half-written: keep the last set */ return usernames.set; }
+    usernames = { mtime, set: new Set(Object.values(all).map((p) => p && typeof p.username === 'string' && p.username.toLowerCase()).filter(Boolean)) };
+  }
+  return usernames.set;
+}
+
+/** Personas created since sinceMs, for "joined" lines in project channels. Read fresh: the collector writes them in its own thread. */
+export function personasSince(sinceMs) {
+  let all = {};
+  try { all = JSON.parse(fs.readFileSync(FILE, 'utf8')) || {}; } catch { return []; }
+  return Object.entries(all).filter(([, p]) => p && p.createdAt >= sinceMs).map(([id, p]) => ({ id, ...p }));
+}