@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/hub/keepawake/agent.mjs

@@ -0,0 +1,96 @@
+// agents-hub keepawake/agent.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Keeps the Mac awake for the hub. Every 30 s it reads the keep-awake mode and holds exactly one `caffeinate` while the
+// Mac should stay awake, reporting to state/keepawake-status.json (read by store.keepAwakeStatus). Runs as the
+// LaunchAgent that keepawake/install.mjs loads.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import { KEEPAWAKE_STATUS, readSettings } from '../lib/store.mjs';
+import { runnerDb } from '../home.mjs';
+
+export const TICK_MS = 30e3;
+export const AGENTS_RECENT_MS = 10 * 60e3;
+const DB = runnerDb();
+
+/** `always` holds the Mac awake, `agents` only while an agent was heard from in the last 10 min, anything else never. */
+export function shouldStayAwake(mode, { lastAgentAt = 0, now }) {
+  if (mode === 'always') return true;
+  if (mode === 'agents') return lastAgentAt > 0 && now - lastAgentAt < AGENTS_RECENT_MS;
+  return false;
+}
+
+/** When any agent or orchestrator last reached the hub, from hub.db opened read-only; 0 when unknown. */
+export function lastAgentAt(file = DB) {
+  let db = null;
+  try {
+    db = new DatabaseSync(file, { readOnly: true });
+    const r = db.prepare(`SELECT MAX(p.last_seen) AS at FROM presence p JOIN actors a ON a.id = p.actor_id
+      WHERE a.node_type IN ('agent', 'orchestrator')`).get();
+    return Number(r && r.at) || 0;
+  } catch { return 0; } finally { try { if (db) db.close(); } catch { /* closed */ } }
+}
+
+/**
+ * -ims prevents idle, system and disk sleep but lets the display sleep. -w ties the child to this process, so even a
+ * killed helper never leaves a caffeinate behind.
+ */
+export const CAFFEINATE_ARGS = (pid = process.pid) => ['-ims', '-w', String(pid)];
+const caffeinate = () => spawn('/usr/bin/caffeinate', CAFFEINATE_ARGS(), { stdio: 'ignore' });
+
+/** Holds at most one caffeinate child: started when asked to stay awake, killed when not, restarted if it died. */
+export function createKeeper({ start = caffeinate, now = Date.now } = {}) {
+  let child = null;
+  let since = null;
+  const drop = (c) => { if (child === c) { child = null; since = null; } };
+  return {
+    set(awake) {
+      if (awake && !child) {
+        const c = start();
+        child = c;
+        since = now();
+        c.on('exit', () => drop(c));
+        c.on('error', (e) => { console.error(`caffeinate failed: ${e.message}`); drop(c); });
+      } else if (!awake && child) {
+        const c = child;
+        drop(c);
+        c.kill();
+      }
+      return { running: !!child, since };
+    },
+  };
+}
+
+export function writeStatus(file, status) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(status));
+  fs.renameSync(tmp, file);
+}
+
+function main() {
+  const keeper = createKeeper();
+  const tick = () => {
+    try {
+      const { mode } = readSettings().keepAwake;
+      const now = Date.now();
+      const state = keeper.set(shouldStayAwake(mode, { lastAgentAt: mode === 'agents' ? lastAgentAt() : 0, now }));
+      writeStatus(KEEPAWAKE_STATUS, { ...state, mode, heartbeat: now, pid: process.pid });
+    } catch (e) { console.error(`keep-awake tick failed: ${e.message}`); }
+  };
+  tick();
+  const timer = setInterval(tick, TICK_MS);
+  const quit = () => {
+    clearInterval(timer);
+    keeper.set(false);
+    try { writeStatus(KEEPAWAKE_STATUS, { running: false, since: null, heartbeat: 0, stoppedAt: Date.now() }); } catch { /* best effort */ }
+    process.exit(0);
+  };
+  process.on('SIGTERM', quit);
+  process.on('SIGINT', quit);
+  process.on('exit', () => keeper.set(false));
+  console.log(`keep-awake helper running (pid ${process.pid})`);
+}
+
+const invoked = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) main();

package/src/hub/lib/brief.mjs

@@ -0,0 +1,133 @@
+// agents-hub lib/brief.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// The written brief for a work stream: brief.md beside the channel, the spec its KICKOFF names, or the KICKOFF body.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parsePosts } from './channels.mjs';
+
+const MAX_CHARS = 12000;
+const MAX_SECTIONS = 24;
+const SPEC_PATH = /(?:^|\s)(?:Spec:\s*)?(docs\/[A-Za-z0-9._/-]+\.md)/;
+const H2 = /^(#{1,2})\s+(.+)$/;
+const NAMED = /^(?:\*\*(.+?)\*\*|([A-Z][A-Za-z0-9 /&-]{2,48}):)\s*$/;
+/** Standing protocol sections — not what the agent was asked to build. */
+const SKIP = /^(workflow\b.*|hard rules|standing rules|browser\b.*|return\b.*|protocol|never|unattended|communicating)$/i;
+
+function safeFile(root, rel) {
+  if (!rel || rel.includes('\0') || rel.includes('..')) return null;
+  let realRoot;
+  try { realRoot = fs.realpathSync(root); } catch { return null; }
+  const candidate = path.resolve(root, rel);
+  let real;
+  try { real = fs.realpathSync(candidate); } catch { return null; }
+  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) return null;
+  try { if (!fs.statSync(real).isFile()) return null; } catch { return null; }
+  return real;
+}
+
+/** At most `bytes` of a regular file; never blocks on a FIFO or reads a device. */
+export function readCapped(file, bytes = MAX_CHARS * 4) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+    if (!fs.fstatSync(fd).isFile()) return null;
+    const buf = Buffer.alloc(bytes);
+    const n = fs.readSync(fd, buf, 0, bytes, 0);
+    return buf.subarray(0, n).toString('utf8');
+  } catch { return null; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+const readText = (file) => readCapped(file);
+
+/** Split a markdown brief into a title and ## / named sections. */
+export function parseBriefSections(text, { maxChars = MAX_CHARS } = {}) {
+  const raw = String(text || '').replace(/\r/g, '').slice(0, maxChars);
+  const titleMatch = raw.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].replace(/[*`]/g, '').trim() : null;
+  const sections = [];
+  let heading = null;
+  let buf = [];
+  const flush = () => {
+    const body = buf.join('\n').trim();
+    buf = [];
+    if (!heading) {
+      if (!body) return;
+      heading = 'Overview';
+    }
+    if (body) sections.push({ heading, body });
+  };
+  for (const line of raw.split('\n')) {
+    const h2 = line.match(H2);
+    if (h2) {
+      const name = h2[2].replace(/[*`]/g, '').trim();
+      if (h2[1] === '#' && title && name === title) continue;
+      if (h2[1] === '#' && !title) {
+        flush();
+        heading = name;
+        continue;
+      }
+      if (h2[1] === '##') {
+        flush();
+        heading = name;
+        continue;
+      }
+    }
+    const named = line.match(NAMED);
+    if (named) {
+      flush();
+      heading = (named[1] || named[2]).replace(/[*`]/g, '').trim();
+      continue;
+    }
+    buf.push(line);
+  }
+  flush();
+  const kept = sections.filter((s) => !SKIP.test(s.heading)).slice(0, MAX_SECTIONS);
+  return { title, sections: kept.length ? kept : sections.slice(0, MAX_SECTIONS) };
+}
+
+const hasBody = (b) => !!(b && b.sections && b.sections.some((s) => s.body && s.body.trim()));
+
+function fromMarkdown(file, source) {
+  const text = readText(file);
+  if (!text) return null;
+  const parsed = parseBriefSections(text);
+  if (!parsed.title && !parsed.sections.length) return null;
+  return { source, ...parsed };
+}
+
+function kickoffOf(channelFile) {
+  try {
+    const st = fs.statSync(channelFile);
+    const posts = parsePosts(fs.readFileSync(channelFile, 'utf8'), st.mtimeMs, undefined, { full: true });
+    return posts.find((p) => /^KICKOFF/.test(p.type.toUpperCase())) || null;
+  } catch { return null; }
+}
+
+/**
+ * The task the agents were given for this channel. Prefers brief.md, then the spec named in KICKOFF, then the
+ * KICKOFF body. `query` is an optional agent transcript first prompt used when those files are thin.
+ */
+export function readTaskBrief(channelFile, { query = null } = {}) {
+  const dir = path.dirname(channelFile);
+  const briefFile = safeFile(dir, 'brief.md');
+  const briefMd = briefFile ? fromMarkdown(briefFile, 'brief.md') : null;
+  const kick = kickoffOf(channelFile);
+  const kickText = kick ? [kick.head.replace(/^KICKOFF\b[:\s—-]*/i, '').trim(), kick.body].filter(Boolean).join('\n').trim() : '';
+  const specRel = kickText.match(SPEC_PATH);
+  let spec = null;
+  if (specRel) {
+    const repoRoot = path.resolve(dir, '..', '..');
+    const file = safeFile(repoRoot, specRel[1]);
+    if (file) spec = fromMarkdown(file, specRel[1]);
+  }
+  const kickBrief = kickText
+    ? { source: 'kickoff', title: briefMd && briefMd.title, ...parseBriefSections(kickText) }
+    : null;
+  if (kickBrief && !kickBrief.sections.length && kickText.length > 40) {
+    kickBrief.sections = [{ heading: 'Kickoff', body: kickText }];
+  }
+  const fromQuery = query ? { source: 'transcript', ...parseBriefSections(query) } : null;
+  if (fromQuery && !fromQuery.sections.length && query && query.trim()) {
+    fromQuery.sections = [{ heading: 'Details', body: query.trim().slice(0, MAX_CHARS) }];
+  }
+  return [briefMd, spec, fromQuery, kickBrief].find(hasBody) || spec || briefMd || fromQuery || kickBrief || null;
+}

package/src/hub/lib/channels.mjs

@@ -0,0 +1,268 @@
+// agents-hub lib/channels.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Task channels (.agents/<task>/channel.md): finding them, parsing posts with real dates, and reading a work stream's
+// state from the channel protocol: step, open blockers and asks by finding id, and who has the ball.
+import fs from 'node:fs';
+import path from 'node:path';
+import { everyRoleClosed, reopens, streamCloser } from './closure.mjs';
+
+export const STEPS = ['Research', 'Design', 'Mockup', 'Build', 'Review', 'Checks', 'Proof'];
+export const HEADER = /^## \[([A-Z][A-Z0-9 -]*?)\] (\d{1,2}):(\d{2})(?::(\d{2}))?(?: (IST|UTC|GMT))? ([^\n]*)$/;
+const ROLE_ALIASES = { 'PLATFORM-AUDITOR': 'PLATFORM AUDITOR', AUDITOR: 'PLATFORM AUDITOR' };
+export const normRole = (r) => { const u = String(r || '').toUpperCase().trim(); return ROLE_ALIASES[u] || u; };
+const DAY_S = 86400;
+const DAY_JUMP_S = 2 * 3600;
+const MAX_BODY_LINES = 6;
+const FULL_BODY_LINES = 120;
+const FULL_BODY_CHARS = 8000;
+
+/** The first markdown heading of a file (a brief or spec title), or null. */
+export function firstHeading(file) {
+  let fd;
+  try {
+    const st = fs.lstatSync(file);
+    if (!st.isFile()) return null;
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const buf = Buffer.alloc(4000);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    const m = buf.subarray(0, n).toString('utf8').match(/^#\s+(.+)$/m);
+    return m ? m[1].replace(/[*`]/g, '').trim() : null;
+  } catch { return null; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+/** Every channel under roots/<repo>/.agents/<task>/channel.md changed since sinceMs. key = "<repo>/<task>". */
+export function channelFiles(roots, sinceMs) {
+  const out = [];
+  for (const root of roots) {
+    let repos = [];
+    try { repos = fs.readdirSync(root); } catch { continue; }
+    for (const repo of repos) {
+      const dir = path.join(root, repo, '.agents');
+      let tasks = [];
+      try { tasks = fs.readdirSync(dir); } catch { continue; }
+      for (const task of tasks) {
+        const file = path.join(dir, task, 'channel.md');
+        try { const st = fs.statSync(file); if (st.isFile() && st.mtimeMs >= sinceMs) out.push({ key: `${repo}/${task}`, task, repo, file, mtime: st.mtimeMs }); } catch { /* none */ }
+      }
+    }
+  }
+  return out;
+}
+
+const ids = (s) => [...new Set((String(s).match(/#[A-Z]?\d+/g) || []).map((x) => x.slice(1)))];
+
+/**
+ * Posts from a channel's text, oldest first. Headers carry a time but no date: the last post is on the file's
+ * modified day, and walking backwards a clock that jumps forward by more than 2 h means the day before. UTC/GMT
+ * times are converted to local time first.
+ */
+export function parsePosts(text, mtime, utcOffsetS = -new Date(mtime).getTimezoneOffset() * 60, { full = false } = {}) {
+  const lines = String(text).replace(/\r/g, '').split('\n');
+  const raw = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(HEADER);
+    if (!m) continue;
+    const body = [];
+    const fullBody = [];
+    for (let j = i + 1; j < lines.length && !HEADER.test(lines[j]); j++) {
+      if (lines[j].trim() && body.length < MAX_BODY_LINES) body.push(lines[j].trim());
+      if (full && fullBody.length < FULL_BODY_LINES) fullBody.push(lines[j].trimEnd());
+      if (!full && body.length >= MAX_BODY_LINES) break;
+    }
+    const head = m[6].trim();
+    let sec = +m[2] * 3600 + +m[3] * 60 + +(m[4] || 0) + (m[5] === 'UTC' || m[5] === 'GMT' ? utcOffsetS : 0);
+    const shift = Math.floor(sec / DAY_S);
+    sec -= shift * DAY_S;
+    const post = { role: normRole(m[1]), sec, shift, head, type: head.split(/ [—(-] | — /)[0].trim().slice(0, 40), text: [head, ...body].join(' ').slice(0, 900), ids: ids(head) };
+    if (full) post.body = fullBody.join('\n').trim().slice(0, FULL_BODY_CHARS);
+    raw.push(post);
+  }
+  const mt = new Date(mtime);
+  const day = new Date(mt.getFullYear(), mt.getMonth(), mt.getDate());
+  let later = mt.getHours() * 3600 + mt.getMinutes() * 60 + mt.getSeconds() + 600;
+  for (let k = raw.length - 1; k >= 0; k--) {
+    if (raw[k].sec > later + DAY_JUMP_S) day.setDate(day.getDate() - 1);
+    later = raw[k].sec;
+    raw[k].at = day.getTime() + raw[k].sec * 1000;
+    delete raw[k].sec;
+    delete raw[k].shift;
+  }
+  return raw;
+}
+
+const isReviewer = (r) => r.includes('REVIEWER');
+const isCoder = (r) => r.includes('CODER');
+const isAuditor = (r) => r.includes('AUDITOR');
+const ballOf = (role) => (isReviewer(role) ? 'REVIEWER' : isAuditor(role) ? 'AUDITOR' : isCoder(role) ? 'CODER' : role === 'ARCHITECT' ? 'ARCHITECT' : null);
+/** Posts that do not move the work: they never change who has the ball. */
+const CHATTER = /^(WAITING|STATUS|JOINED|POST|NOTE|ACK(?! COMMITTED)|STOPPING|STOOD DOWN|HEARTBEAT|PROGRESS)/;
+/** A post that moves the work: an agent's, and not a check-in such as the scheduled STATUS. */
+export const movesWork = (p) => p.role !== 'USER' && !CHATTER.test(p.type.toUpperCase());
+/** The step one header implies on its own (0 when it implies none); a stream's step is the running maximum of these. */
+export function postStep(p) {
+  const t = p.type.toUpperCase();
+  let step = 0;
+  if (/^(PLAN|INVENTORY|DESIGN)/.test(t)) step = 1;
+  if (/MOCKUP/.test(t)) step = 2;
+  if (isCoder(p.role) && /^(STARTED|READY|RESOLVED|FIXED|COMMITTED)/.test(t)) step = 3;
+  if (isReviewer(p.role) && /^(REVIEW\b|FINDINGS|MAJOR|MINOR|CHANGES|APPROVED|VERIFIED|ACK COMMITTED)/.test(t)) step = 4;
+  if (/^(DEPLOYED|DEPLOY POINT|MERGED|LIVE CHECK)/.test(t)) step = 5;
+  if (/EVIDENCE/.test(t)) step = 6;
+  return step;
+}
+/** What keeps a FINAL header from being a pass: a failure, a hold, or an explicit "not a sign-off". */
+const FINAL_HOLD = /\bFAIL(ED|S)?\b|\bBLOCKED\b|\bPENDING\b|\bWAITING\b|\bSTARTING\b|\bNOT (A )?(RELEASE )?SIGN-OFF\b/;
+export const isFinalFail = (head) => /^FINAL\b/.test(head) && /\bFAIL(ED|S)?\b/.test(head);
+/**
+ * A reviewer's final pass. Real headers vary ("FINAL: PASS", "FINAL (qa) — … all APPROVED", "FINAL — S2: APPROVED.",
+ * bare "FINAL (W3)"), so any FINAL counts unless it is held; "FINAL REVIEW …" counts only when it says PASS/APPROVED.
+ */
+export const isFinalPass = (head) => /^FINAL\b/.test(head) && !FINAL_HOLD.test(head) && (!/^FINAL REVIEW\b/.test(head) || /\b(PASS|APPROVED)\b/.test(head));
+const USER_CHANGES = /^CHANGES REQUESTED\b/;
+const NOT_BLOCKING = /\bNOT BLOCKING\b|\bNON-BLOCKING\b|\bNO BLOCKERS?\b|\bBLOCKERS?:\s*NONE\b|\b0 BLOCKERS?\b/;
+const NEEDS_USER = /\bNEEDS USER\b/;
+/** An agent tagging you in a post ("@you", or "@user"): it needs your input, the same as a NEEDS USER header. */
+export const MENTIONS_YOU = /(^|[\s(\[*_"'])@(you|user)\b/i;
+/** A handle the user also goes by ("aagarwal1", "AdaLovelace"): what may follow an "@" as a tag for them. */
+export const USER_ALIAS = /^[A-Za-z0-9][A-Za-z0-9_.-]{1,38}[A-Za-z0-9]$/;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+let aliasCache = { key: '', re: null };
+function aliasMention(aliases) {
+  const list = (aliases || []).filter((a) => typeof a === 'string' && USER_ALIAS.test(a));
+  const key = list.join('|');
+  if (key !== aliasCache.key) aliasCache = { key, re: list.length ? new RegExp(`(^|[\\s(\\[*_"'])@(${list.map(escapeRe).join('|')})\\b(?![.-]\\w)`, 'i') : null };
+  return aliasCache.re;
+}
+/** "@you"/"@user", or "@" one of the user's handles; a handle never matches inside an email, a domain or a longer word. */
+export function mentionsYou(text, aliases = []) {
+  if (MENTIONS_YOU.test(text)) return true;
+  const re = aliasMention(aliases);
+  return !!re && re.test(text);
+}
+const NEEDS_USER_SETTLED = /\bNO NEEDS USER\b|NEEDS USER (ITEMS? )?(SETTLED|RESOLVED|CLOSED|ANSWERED|DECIDED)/;
+const CODER_REPLY = /^(READY|RESOLVED|FIX(ED|ES)?\b)/;
+/** A closing word that is not negated ("NOT RESOLVED", "still not fixed", "isn't addressed" do not close). */
+const CLOSES = /(?<!\b(?:NOT|NEVER|STILL NOT|ISN'T|AREN'T|WASN'T)\s)\b(RESOLVED|FIX(ED|ES)?|ADDRESSED|WITHDRAWN|CLOSED|SATISFIED)\b/;
+
+/** Who a QUESTION is for: "QUESTION FOR CODER" goes to the coder; otherwise the architect answers. */
+const questionFor = (head) => (/\b(FOR|TO) (THE )?CODER\b/.test(head) ? 'CODER' : /\b(FOR|TO) (THE )?REVIEWER\b/.test(head) ? 'REVIEWER' : 'ARCHITECT');
+
+/** Who must act next after a post, or null when the post does not decide it. */
+function ballAfter(p) {
+  const t = p.type.toUpperCase();
+  const head = p.head.toUpperCase();
+  const r = p.role;
+  if (/^QUESTION/.test(t) && r !== 'ARCHITECT') return questionFor(head);
+  if (r === 'USER') return USER_CHANGES.test(t) ? 'CODER' : /^DECISION/.test(t) ? 'ARCHITECT' : null;
+  if (isCoder(r)) {
+    if (CODER_REPLY.test(t)) return 'REVIEWER';
+    if (/^(COMMITTED|DONE|DEPLOY POINT)/.test(t)) return 'ARCHITECT';
+    return null;
+  }
+  if (isReviewer(r)) {
+    if (isFinalFail(head)) return 'CODER';
+    if (isFinalPass(head)) return 'ARCHITECT';
+    if (/^(APPROVED|CHANGES|FINDINGS|MAJOR|MINOR|BLOCKER|REVIEW\b|NOT ACKED)/.test(t)) return 'CODER';
+    if (/^(ACK COMMITTED|VERIFIED|COMMIT VERIFIED|LIVE CHECK)/.test(t)) return 'ARCHITECT';
+    if (/^FINAL REVIEW/.test(t)) return 'REVIEWER';
+    return null;
+  }
+  if (isAuditor(r)) return /\b(BLOCKER|MAJOR)\b/.test(head) && !NOT_BLOCKING.test(head) ? 'CODER' : null;
+  if (r === 'ARCHITECT') {
+    if (/^(DEPLOYED|EVIDENCE|MERGED)/.test(t)) return 'REVIEWER';
+    if (/^(KICKOFF|ANSWER|RULING|NUDGE|NEW STEP|PLAN)/.test(t)) return 'CODER';
+    return null;
+  }
+  return null;
+}
+
+/** A work stream's state from its posts, oldest first. `aliases`: the user's handles, which tag them like "@you". */
+export function analyseStream(posts, { aliases = [] } = {}) {
+  let step = 0; let round = 0; let done = false; let failed = null; let question = null; let ball = null; let ballAt = null;
+  let outcome = null; let agentBall = null;
+  let lastFinal = null; let lastEvidence = null; let lastCoderReplyAt = 0;
+  const blockers = new Map();
+  const asks = new Map();
+  const lastByRole = {};
+  const closeBy = (pred) => { for (const [k, b] of blockers) if (pred(b)) blockers.delete(k); };
+  posts.forEach((p, i) => {
+    const t = p.type.toUpperCase();
+    const head = p.head.toUpperCase();
+    lastByRole[p.role] = p;
+    if (isCoder(p.role) && /^READY/.test(t)) { round++; if (done || failed) { done = false; failed = null; step = Math.min(step, 4); } }
+    step = Math.max(step, postStep(p));
+    if (isCoder(p.role) && CODER_REPLY.test(t)) { lastCoderReplyAt = p.at; if (failed && !/^READY/.test(t)) failed = null; }
+    if (/EVIDENCE/.test(t)) lastEvidence = p;
+    const passes = (isReviewer(p.role) && isFinalPass(head)) || /^RELEASED/.test(t);
+    if (isReviewer(p.role) && isFinalFail(head)) { failed = p; done = false; }
+    else if (p.role === 'USER' && USER_CHANGES.test(t)) { failed = p; done = false; lastFinal = null; }
+    else if (passes) { done = true; failed = null; lastFinal = p; }
+    const closes = !passes && streamCloser(p);
+    if (closes) { done = true; failed = null; outcome = closes; } else if (passes) outcome = 'passed';
+    if (done && reopens(p)) done = false;
+
+    const raisesBlocker = !isCoder(p.role) && p.role !== 'USER' && !passes && !closes && !CLOSES.test(head)
+      && /\bBLOCKER\b|DEPLOY BLOCKED|CHANGES REQUESTED/.test(head) && !NOT_BLOCKING.test(head);
+    if (raisesBlocker) {
+      for (const id of p.ids.length ? p.ids : [`p${i}`]) blockers.set(`${p.role}:${id}`, { id, role: p.role, at: p.at, text: p.text });
+      if (done) { done = false; lastFinal = null; }
+    }
+    if (!raisesBlocker && p.ids.length && (CLOSES.test(head) || (p.role === 'ARCHITECT' && /^(RULING|ANSWER)/.test(t)))) closeBy((b) => p.ids.includes(b.id));
+    if (isReviewer(p.role) && (/^APPROVED/.test(t) || passes)) closeBy((b) => isReviewer(b.role));
+    if (isAuditor(p.role) && /ALIGNMENT OK|FINAL/.test(head)) closeBy((b) => isAuditor(b.role));
+    if (p.role === 'ARCHITECT' && /^(DEPLOYED|MERGED)/.test(t)) closeBy((b) => b.role === 'ARCHITECT');
+
+    const opensAsk = p.role !== 'USER' && (NEEDS_USER.test(head) || mentionsYou(p.text, aliases)) && !NEEDS_USER_SETTLED.test(head) && !/^(ANSWER|RULING)/.test(t);
+    const settles = (p.role === 'USER' && /^(DECISION|CHANGES REQUESTED)/.test(t))
+      || (p.role === 'ARCHITECT' && /^(ANSWER|RULING|NEW STEP)/.test(t) && /USER DECI|PER (THE )?USER|USER APPROVED|USER CHOSE/.test(p.text.toUpperCase()))
+      || (NEEDS_USER_SETTLED.test(head) && p.ids.length);
+    if (opensAsk) asks.set(p.ids[0] || `p${i}`, p);
+    else if (settles) {
+      const keys = p.ids.length ? p.ids.filter((id) => asks.has(id)) : [...asks.keys()].slice(-1);
+      for (const k of keys) asks.delete(k);
+    }
+
+    if (/^QUESTION/.test(t) && p.role !== 'ARCHITECT' && questionFor(head) === 'ARCHITECT') question = p;
+    else if (p.role === 'ARCHITECT' && /\b(ANSWERS?|RULINGS?|RE: QUESTION|DECISION)\b/.test(head)) question = null;
+
+    if (!CHATTER.test(t)) { const b = ballAfter(p); if (b) { ball = b; ballAt = p.at; if (p.role !== 'USER') agentBall = b; } }
+  });
+  if (!done && !failed) { const all = everyRoleClosed(posts, agentBall); if (all) { done = true; outcome = all; } }
+  if (!done) outcome = null;
+  if (done) { asks.clear(); question = null; blockers.clear(); }
+  const open = [...blockers.values()];
+  const needsUser = [...asks.values()].pop() || null;
+  let owner = ball;
+  let ownerAt = ballAt;
+  if (needsUser) { owner = 'YOU'; ownerAt = needsUser.at; }
+  else if (failed) { owner = 'CODER'; ownerAt = failed.at; }
+  else if (open.length) {
+    const latest = open.reduce((a, b) => (b.at > a.at ? b : a));
+    if (open.every((b) => b.role === 'ARCHITECT')) { owner = 'ARCHITECT'; ownerAt = latest.at; }
+    else if (lastCoderReplyAt > latest.at) {
+      if (!(ballAt > lastCoderReplyAt)) { owner = ballOf(latest.role) || 'REVIEWER'; ownerAt = lastCoderReplyAt; }
+    } else { owner = 'CODER'; ownerAt = latest.at; }
+  } else if (question) { owner = 'ARCHITECT'; ownerAt = question.at; }
+  if (done) { owner = null; ownerAt = null; }
+  return { step, stepName: STEPS[step], round, done, outcome, failed, blockers: open, needsUser, asks: [...asks.values()], question, ball: owner, ballAt: ownerAt, lastByRole, lastFinal, lastEvidence };
+}
+
+/** Does a channel role ("UI CODER", "PLATFORM AUDITOR") hold the ball named by analyseStream ("CODER", "REVIEWER", …)? */
+export function holds(role, ball) {
+  if (!ball || !role) return false;
+  if (ball === 'CODER') return isCoder(role);
+  if (ball === 'REVIEWER') return isReviewer(role);
+  if (ball === 'AUDITOR') return isAuditor(role);
+  return role === ball;
+}
+
+/**
+ * A user decision as channel text: one header line, then the text with every line that could read as a header
+ * (or any markdown heading) quoted, so it can never forge a post from another role.
+ */
+export function decisionPost(text, { ref = null, at = new Date(), kind = 'DECISION' } = {}) {
+  const hhmmss = [at.getHours(), at.getMinutes(), at.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+  const safeRef = ref && /^[A-Z]?\d+$/.test(ref) ? ` #${ref}` : '';
+  const type = ['CHANGES REQUESTED', 'MESSAGE'].includes(kind) ? kind : 'DECISION';
+  const body = String(text).split(/\r\n|[\n\r\v\f\x1c-\x1e\x85\u2028\u2029]/).map((l) => (/^\s*#/.test(l) ? `> ${l}` : l)).join('\n').trim();
+  return `\n## [USER] ${hhmmss} ${type}${safeRef}\n${body}\n`;
+}

package/src/hub/lib/chat.mjs

@@ -0,0 +1,163 @@
+// agents-hub lib/chat.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Chat: task channels are the agents' own .agents/<task>/channel.md files; project channels live in the hub and get
+// milestones from the hub agent (a stream starting, passing or failing final review) next to what you post.
+import fs from 'node:fs';
+import path from 'node:path';
+import { channelFiles, decisionPost, firstHeading, isFinalFail, isFinalPass, mentionsYou, normRole, parsePosts } from './channels.mjs';
+import { projectOf } from './deliveries.mjs';
+import { personasSince } from './personas.mjs';
+import { HUB } from './store.mjs';
+
+const CHAT = path.join(HUB, 'state', 'chat');
+const MAX_MESSAGES = 300;
+const PROJECT = /^[A-Za-z0-9._-]{1,80}$/;
+fs.mkdirSync(CHAT, { recursive: true });
+
+const projectFile = (p) => path.join(CHAT, `project-${p}.jsonl`);
+const LIVE = path.join(HUB, 'state', 'live');
+/** Only real Cursor conversations (transcript ids) have a hook that can claim bus mail. */
+const SESSION_ID = /^[A-Za-z0-9-]{8,80}$/;
+export const hasChatInbox = (id) => SESSION_ID.test(id);
+
+function readLog(file) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  return text.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter((m) => m && Number.isFinite(m.at) && typeof m.text === 'string' && typeof m.from === 'string');
+}
+const readProjectLog = (p) => readLog(projectFile(p));
+
+/** Leftover live/*.json from before the SQLite hook; presence now lives in hub.db. */
+export function liveOf(id) {
+  if (!SESSION_ID.test(id)) return null;
+  try { const v = JSON.parse(fs.readFileSync(path.join(LIVE, `${id}.json`), 'utf8')); return Number.isFinite(v.at) ? { at: v.at, event: String(v.event || ''), tool: typeof v.tool === 'string' ? v.tool : null } : null; } catch { return null; }
+}
+
+/** Every task channel changed since sinceMs, and one project channel per project they belong to. */
+export function listChannels(roots, sinceMs) {
+  const tasks = channelFiles(roots, sinceMs).map((c) => ({
+    id: `task:${c.key}`, kind: 'task', key: c.key, name: c.task, repo: c.repo, project: projectOf(c.repo) || c.repo,
+    title: firstHeading(path.join(path.dirname(c.file), 'brief.md')), lastAt: c.mtime,
+  }));
+  const names = [...new Set(tasks.map((t) => t.project))];
+  const projects = names.map((p) => {
+    const log = readProjectLog(p);
+    return { id: `project:${p}`, kind: 'project', name: p, project: p, lastAt: Math.max(0, ...tasks.filter((t) => t.project === p).map((t) => t.lastAt), ...log.map((m) => m.at)) };
+  });
+  return { projects: projects.sort((a, b) => b.lastAt - a.lastAt), tasks: tasks.sort((a, b) => b.lastAt - a.lastAt) };
+}
+
+/** Your one-to-one messages copied into a channel (the only inbox a channel-only agent has), old and new wording. */
+const DIRECT_COPY = /^(To the ([a-z0-9 -]+?)(?:, direct from the user[^:]*)?:|@[\w.-]+ \(for the [A-Z0-9 -]+, direct from you\):)/;
+const isDirectCopy = (m) => m.from === 'USER' && m.type === 'MESSAGE' && DIRECT_COPY.test(m.body);
+const REPLY_TYPE = 'REPLY TO USER';
+const isReplyToYou = (m) => m.from !== 'USER' && m.type.toUpperCase().startsWith(REPLY_TYPE);
+const addressee = (m) => { const x = m.body.match(DIRECT_COPY); return x && x[2] ? x[2].trim() : null; };
+
+function allPosts(file) {
+  const st = fs.statSync(file);
+  return parsePosts(fs.readFileSync(file, 'utf8'), st.mtimeMs, undefined, { full: true })
+    .map((p, i) => ({ id: `${p.at}-${i}`, at: p.at, from: p.role, type: p.type, head: p.head, body: p.body || '' }));
+}
+
+const OPTION = /^\s*(?:[-*]\s+)?(?:\*\*)?(?:\(([a-hA-H1-9])\)|([a-hA-H1-9])[).:]|Option\s+([A-Ha-h1-9])\s*[:—-])(?:\*\*)?\s+(.{3,300})$/;
+const NEEDS_YOU = /NEEDS USER|USER DECISION|DECISION NEEDED|FOR (THE )?USER/i;
+
+/** The choices a post offers ("(a) …", "B) …", "Option 2: …"), in order, when there are at least two. */
+export function optionsIn(body) {
+  const out = [];
+  for (const line of String(body || '').split('\n')) {
+    const m = line.match(OPTION);
+    if (m) out.push({ key: (m[1] || m[2] || m[3]).toLowerCase(), text: m[4].replace(/\*\*/g, '').trim() });
+  }
+  const keys = out.map((o) => o.key);
+  return out.length >= 2 && new Set(keys).size === keys.length ? out : [];
+}
+
+/**
+ * What a NEEDS USER ask is, from its channel: the post itself (full text), who raised it and when, the posts before it
+ * about the same finding, and any options it lists. `ref` is the finding id ("A9"); `at` picks the post when there is none.
+ */
+export function askDetail(file, { ref = null, at = null, aliases = [] } = {}) {
+  const posts = allPosts(file).filter((m) => !isDirectCopy(m) && !isReplyToYou(m));
+  const id = ref ? ref.replace(/[^A-Za-z0-9]/g, '') : '';
+  const refRe = id ? new RegExp(/^[A-Za-z]/.test(id) ? `(?:#|\\b)${id}\\b` : `#${id}\\b`) : null;
+  const mentions = (m) => !!refRe && refRe.test(`${m.head}\n${m.body}`);
+  const asksYou = (m) => m.from !== 'USER' && (NEEDS_YOU.test(m.head) || mentionsYou(`${m.head}\n${m.body}`, aliases));
+  const target = (at && posts.find((m) => Math.abs(m.at - at) < 1000 && asksYou(m)))
+    || [...posts].reverse().find((m) => asksYou(m) && (!ref || mentions(m)))
+    || null;
+  if (!target) return null;
+  const related = ref ? posts.filter((m) => m !== target && mentions(m) && m.at <= target.at).slice(-8) : [];
+  const after = posts.filter((m) => m.at > target.at && m.from !== 'USER').slice(-3);
+  return {
+    post: { from: target.from, at: target.at, head: target.head, type: target.type, body: target.body },
+    options: optionsIn(target.body),
+    related: related.map((m) => ({ from: m.from, at: m.at, head: m.head, body: m.body.slice(0, 1500) })),
+    since: after.map((m) => ({ from: m.from, at: m.at, head: m.head })),
+  };
+}
+
+/** A task channel as chat messages: every post with its full body, except one-to-one traffic with you. */
+export function taskMessages(file) {
+  return allPosts(file).filter((m) => !isDirectCopy(m) && !isReplyToYou(m)).slice(-MAX_MESSAGES);
+}
+
+/**
+ * An agent known only from its channel posts ("<repo>/<task>:<ROLE>"). It has no bus inbox; it hears you only through
+ * its task channel.
+ */
+export function channelParticipant(id) {
+  const m = String(id || '').match(/^([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+):([A-Z][A-Z0-9 -]{0,39})$/);
+  return m ? { key: m[1], role: normRole(m[2]) } : null;
+}
+
+/** A direct message to a channel-only agent, as a USER MESSAGE post that names its role and how to answer. */
+export const participantPost = (role, text) => decisionPost(
+  `To the ${role.toLowerCase()}, direct from the user (answer in this channel with a post of type ${REPLY_TYPE}, e.g. "## [${role}] <time> ${REPLY_TYPE}"): ${text}`, { kind: 'MESSAGE' });
+
+/** The one-to-one with a channel-only agent: your messages to its role and its REPLY TO USER posts, nothing else. */
+export function participantThread(file, role) {
+  const mine = role.toLowerCase();
+  return allPosts(file)
+    .filter((m) => (isDirectCopy(m) && addressee(m) === mine) || (isReplyToYou(m) && normRole(m.from) === role))
+    .map((m) => (m.from === 'USER' ? { ...m, body: m.body.replace(DIRECT_COPY, '').trim() } : m))
+    .slice(-MAX_MESSAGES);
+}
+
+/** A project channel: what people posted, plus the hub agent's milestones from that project's task channels. */
+export function projectMessages(roots, project, sinceMs) {
+  if (!PROJECT.test(project)) return null;
+  const out = readProjectLog(project).map((m, i) => ({ id: `p-${m.at}-${i}`, at: m.at, from: m.from, type: 'MESSAGE', head: '', body: m.text }));
+  for (const c of channelFiles(roots, sinceMs)) {
+    if ((projectOf(c.repo) || c.repo) !== project) continue;
+    const title = firstHeading(path.join(path.dirname(c.file), 'brief.md')) || c.task;
+    let posts = [];
+    try { posts = parsePosts(fs.readFileSync(c.file, 'utf8'), c.mtime); } catch { continue; }
+    let started = false;
+    for (const p of posts) {
+      const head = p.head.toUpperCase();
+      let milestone = null;
+      if (/^KICKOFF/.test(p.type.toUpperCase())) { if (!started) milestone = ['start', `${title} started`]; started = true; }
+      else if (p.role.includes('REVIEWER') && isFinalFail(head)) milestone = ['alert', `${title} failed final review`];
+      else if (p.role.includes('REVIEWER') && isFinalPass(head)) milestone = ['celebrate', `${title} passed final review`];
+      else if (/^RELEASED/.test(head)) milestone = ['celebrate', `${title} was released`];
+      if (milestone) out.push({ id: `m-${c.key}-${p.at}`, at: p.at, from: 'HUB', type: milestone[0], head: '', body: milestone[1], stream: c.task });
+    }
+  }
+  for (const p of personasSince(sinceMs)) {
+    if (!p.channel || !p.role || p.role === 'ARCHITECT') continue;
+    const [repo, task] = p.channel.split('/');
+    if ((projectOf(repo) || repo) !== project) continue;
+    out.push({ id: `j-${p.id}`, at: p.createdAt, from: 'HUB', type: 'joined', head: '', body: `${p.name} (@${p.username || p.name}) joined #${task} as ${roleName(p.role)}`, persona: { name: p.name, seed: p.seed, role: p.role }, stream: task });
+  }
+  return out.filter((m) => m.at >= sinceMs).sort((a, b) => a.at - b.at).slice(-MAX_MESSAGES);
+}
+
+const roleName = (r) => (r.includes('AUDITOR') ? 'platform auditor' : r.toLowerCase().replace(/-/g, ' '));
+
+export function postToProject(project, from, text) {
+  if (!PROJECT.test(project)) return false;
+  fs.appendFileSync(projectFile(project), JSON.stringify({ at: Date.now(), from, text: String(text).slice(0, 4000) }) + '\n');
+  return true;
+}