@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/hub/core/wake.mjs

@@ -0,0 +1,125 @@
+// agents-hub core/wake.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Waking a stopped subagent so it can read your message. Nothing outside Cursor can start a turn in a chat; a finished
+// subagent can be resumed only by the session that started it (Task tool, by id). So the hub asks that parent, once,
+// and again after WAKE_AGAIN_MS if your message is still waiting.
+import { ADDRESS, managerChats } from './ids.mjs';
+import { edgeId } from './edgeIds.mjs';
+
+export const WAKE_AGAIN_MS = 15 * 60e3;
+/** No hook event for this long: the subagent is not running (long commands can be silent for minutes). */
+export const STOPPED_MS = 5 * 60e3;
+
+const wakeText = (name, id) => `The user sent a direct message to your subagent ${name || id} (${id}), which looks stopped. `
+  + `Resume it now with the Task tool (resume: "${id}", run_in_background: true). Its message is already queued in its own bus inbox; `
+  + 'tell it to answer that message and then carry on if work remains. If it is in fact still running, do nothing. Do not answer in its place.';
+
+/** Ask a subagent's parent to resume it. Returns the wake record, or null when it has no parent the hub can reach. */
+export function requestWake(hub, childId, { name = null, now = Date.now() } = {}) {
+  const { registry, messaging } = hub;
+  const child = registry.get(childId);
+  if (!child || !child.parent_id || !ADDRESS.test(child.parent_id) || child.parent_id === childId) return null;
+  if (registry.fact('run', childId)) return null;
+  const prior = registry.fact('wake', childId);
+  if (prior && now - prior.at < WAKE_AGAIN_MS) return prior;
+  const env = messaging.publish({
+    id: edgeId('w', childId, Math.floor(now / WAKE_AGAIN_MS)), from: 'manager', fromName: 'Manager', topic: `agent/${child.parent_id}`, type: 'WAKE_CHILD', needsAck: true,
+    body: wakeText(name || child.persona_name || child.role, childId),
+  }, registry.directory());
+  if (env.error || !env.to.length) return null;
+  const record = { at: now, parent: child.parent_id, messageId: env.id };
+  registry.setFact('wake', childId, record);
+  return record;
+}
+
+/** The scheduled nudge reaches agents heard from this recently, at most NUDGE_CAP per tick. */
+export const NUDGE_LIVE_MS = 3 * 3600e3;
+export const NUDGE_CAP = 50;
+
+export const nudgeDue = (last, everyMin, now) => everyMin > 0 && (!Number.isFinite(last) || last > now || now - last >= everyMin * 60e3);
+
+/**
+ * Who gets this tick's scheduled nudge: agents and orchestrators heard from within NUDGE_LIVE_MS that are not done,
+ * not excluded and not still holding an earlier scheduled nudge; the longest silent first.
+ */
+export function nudgeTargets({ actors, seen, done = new Set(), pending = new Set(), exclude = new Set(), now, cap = NUDGE_CAP }) {
+  return actors
+    .filter((a) => (a.node_type === 'agent' || a.node_type === 'orchestrator') && ADDRESS.test(a.id) && a.id !== 'user' && a.id !== 'manager')
+    .filter((a) => !done.has(a.id) && !pending.has(a.id) && !exclude.has(a.id))
+    .map((a) => ({ id: a.id, seenAt: seen.get(a.id) || 0 }))
+    .filter((a) => a.seenAt > 0 && now - a.seenAt < NUDGE_LIVE_MS)
+    .sort((a, b) => a.seenAt - b.seenAt)
+    .slice(0, cap);
+}
+
+const nudgeText = (every) => `Scheduled check-in from the hub (every ${every} min). Status is mandatory: post your current state in your task channel now. `
+  + 'Post `STATUS` if you are working or waiting (say on whom), `BLOCKER` if you are stuck, or your terminal post '
+  + '(`DONE`, `FINAL: PASS` / `FINAL: FAIL`, `STOPPED — <reason>`, `HANDED OVER — <to whom>`) if you have finished. '
+  + 'If you have no task channel yet, open `<repo>/.agents/<task>/channel.md` with a `KICKOFF` post stating your task. Then ack this message.';
+
+/**
+ * Agents finished by what the Board shows: a stream whose final review passed, or a done agent row or delivery. Rows
+ * and deliveries are only as fresh as the last collect, so one older than the agent's last sign of life does not count.
+ */
+function doneIds(registry, actors, seen) {
+  const rows = new Map(registry.facts('agent-row').map((r) => [r.key, r]));
+  const deliveries = new Map(registry.facts('delivery').map((d) => [d.key, d]));
+  const done = new Set();
+  for (const a of actors) {
+    const row = rows.get(a.id);
+    const key = a.stream_key || (row && row.streamKey);
+    const stream = key && registry.fact('stream', key);
+    const d = a.node_type === 'orchestrator' && deliveries.get(a.id);
+    const current = (f) => f && f.status === 'done' && f.updated_at >= (seen.get(a.id) || 0);
+    if ((stream && stream.done) || current(row) || current(d)) done.add(a.id);
+  }
+  return done;
+}
+
+/** Send the scheduled nudge when it is due. The last run is kept in hub.db so a restart keeps the cadence. */
+export function scheduledNudge(hub, { everyMin, now = Date.now(), skip = null, released = null } = {}) {
+  const { db, registry, messaging } = hub;
+  const last = (registry.fact('wake', 'scheduled') || {}).at;
+  if (!nudgeDue(last, everyMin, now)) return null;
+  const actors = registry.all();
+  const seen = new Map(actors.map((a) => [a.id, a.last_at || 0]));
+  for (const [id, p] of registry.presences()) seen.set(id, Math.max(seen.get(id) || 0, p.last_seen));
+  // Scheduled and Board nudges ask for an ack; the manager worker's own NUDGE posts do not, so they never hold one back.
+  const pending = new Set(db.prepare(`SELECT DISTINCT d.recipient AS id FROM messages m JOIN deliveries d ON d.message_id = m.id
+    WHERE m.created_at > ? AND m.expires_at > ? AND m.sender = 'manager' AND m.type = 'NUDGE' AND m.needs_reply = 1
+    AND d.state IN ('queued','leased','delivered')`).all(now - NUDGE_LIVE_MS, now).map((r) => r.id));
+  const exclude = new Set(registry.facts('run').map((r) => r.key));
+  for (const chat of managerChats(registry.fact('manager', 'config'))) exclude.add(chat);
+  if (skip) for (const id of skip(last)) exclude.add(id);
+  if (released) for (const id of released()) pending.delete(id);
+  const targets = nudgeTargets({ actors, seen, done: doneIds(registry, actors, seen), pending, exclude, now });
+  const dir = targets.length ? registry.directory(now) : [];
+  const sent = [];
+  for (const t of targets) {
+    const env = messaging.publish({
+      id: edgeId('n', Math.floor(now / (everyMin * 60e3)), t.id), from: 'manager', fromName: 'Manager', topic: `agent/${t.id}`, type: 'NUDGE', body: nudgeText(everyMin),
+      needsAck: true, ttlMs: NUDGE_LIVE_MS, meta: { scheduled: true },
+    }, dir);
+    if (!env.error && env.to.length) sent.push(t.id);
+  }
+  registry.setFact('wake', 'scheduled', { at: now, sent: sent.length });
+  registry.appendEvent({ at: now, kind: 'WAKE', actor: 'manager', payload: {
+    from: 'manager', to: '*', type: 'WAKE', count: sent.length,
+    text: `Scheduled nudge (every ${everyMin} min): ${sent.length} agent${sent.length === 1 ? '' : 's'}`,
+  } });
+  return sent;
+}
+
+/** For every subagent with a message from you still queued and no hook event since it arrived, ask its parent once. */
+export function sweepWakes(hub, now = Date.now()) {
+  const { db, registry } = hub;
+  const rows = db.prepare(`SELECT d.recipient AS id, MIN(m.created_at) AS first FROM deliveries d JOIN messages m ON m.id = d.message_id
+    WHERE m.sender = 'user' AND d.state = 'queued' AND m.expires_at > ? AND m.created_at < ? GROUP BY d.recipient`).all(now, now - 60e3);
+  const woken = [];
+  for (const r of rows) {
+    const seen = registry.presence(r.id);
+    if (seen && (seen.last_seen > r.first || now - seen.last_seen < STOPPED_MS)) continue;
+    const w = requestWake(hub, r.id, { now });
+    if (w && w.at === now) woken.push(r.id);
+  }
+  return woken;
+}

package/src/hub/home.mjs

@@ -0,0 +1,16 @@
+// Where the ported agents-hub core finds the hub it serves. Only the runner child process loads the core, and it sets
+// both variables before it starts; an unset value is a hard error, never a default inside the plugin tree, so the core
+// can't create state next to the plugin or open the frozen hub.db by accident.
+import path from 'node:path';
+
+function required(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} is not set: the hub core runs only inside the Pulse runner process`);
+  return path.resolve(value);
+}
+
+/** The agents-hub folder whose state/ (token, personas, settings, markers, manager files) the runner keeps using. */
+export const hubHome = () => required('PULSE_HUB_HOME');
+
+/** The runner's SQLite file; it holds the hub ledger tables in place of state/hub.db. */
+export const runnerDb = () => required('PULSE_RUNNER_DB');

package/src/hub/hooks/hub-bridge.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// agents-hub hooks/hub-bridge.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+/**
+ * Thin Cursor hook adapter over the hub SQLite ledger.
+ * Reply rules:
+ *  1. Agent-to-agent mail is never auto-captured. The agent answers with `hub bus reply --id <m>`.
+ *  2. A direct message from you is shown mid-turn as a side chat (postToolUse): the agent answers it with
+ *     `bus reply` and keeps working. Nothing it writes is auto-captured for it.
+ *  3. A message from you still unanswered when the turn ends comes back as the next prompt (stop hook);
+ *     only then is the next response captured as the reply to those message ids.
+ *  4. Other mail shown mid-turn includes the id and the reply command. Nothing is auto-captured.
+ * Always fails open: any problem prints {} so the chat is never blocked.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openHub } from '../core/hub.mjs';
+import { hubHome } from '../home.mjs';
+import { CHANNEL_POST_RULE, DECISION_RULE, WRITING_GUIDE } from '../lib/writing.mjs';
+import { isFyi } from '../core/ids.mjs';
+
+const STATE = path.join(hubHome(), 'state');
+const ID = /^[A-Za-z0-9._-]{1,200}$/;
+const REPLY_MAX = 8000;
+/** Cursor stops honouring a stop hook's followup_message after this many automatic follow-ups in a row. */
+const STOP_LOOP_LIMIT = 5;
+const CLI = path.join(hubHome(), 'hub.mjs');
+
+const done = (o = {}) => { process.stdout.write(JSON.stringify(o)); process.exit(0); };
+const clock = (t) => new Date(t).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+
+function splitReaction(raw) {
+  const m = String(raw).match(/^\s*\**React\**:\s*(\p{Extended_Pictographic}(?:\uFE0F|\u200D\p{Extended_Pictographic}|\p{Emoji_Modifier})*)\s*(?:\n|$)/u);
+  return m ? { reaction: m[1], text: raw.slice(m[0].length).trim() } : { reaction: null, text: raw };
+}
+
+function replyHint(ids) {
+  return ids.map((id) => `node ${CLI} bus reply --id ${id} --as <your-address> "<answer>"`).join('\n');
+}
+
+/** A multi-line markdown answer survives the shell only inside a quoted heredoc. */
+function markdownReplyHint(ids) {
+  return ids.map((id) => `node ${CLI} bus reply --id ${id} --as <your-address> "$(cat <<'EOF'\n<your answer in markdown>\nEOF\n)"`).join('\n');
+}
+
+const mailLines = (pending) => pending.map((m) => `[${clock(m.at)}] ${m.fromName || m.from || 'User'} · ${m.type || 'MESSAGE'} · ${m.topic || 'direct'} · id ${m.id}\n${m.text}`).join('\n\n');
+
+/** How to answer the user: the agent's persona voice (attached to each direct message) and the markdown guide. */
+function howToAnswer(pending) {
+  const voice = pending.map((m) => m.meta && m.meta.voice).find((v) => typeof v === 'string' && v);
+  return [voice, WRITING_GUIDE].filter(Boolean).join('\n');
+}
+
+function formatMail(pending, { autoCapture }) {
+  const parts = mailLines(pending);
+  if (autoCapture) {
+    return `Messages delivered by the Agent Hub bus (answer these in this turn; the hub will capture this reply only for these ids):\n${howToAnswer(pending)}\n\n${parts}`;
+  }
+  return `Messages from the Agent Hub bus. They are not auto-captured. Reply with:\n${replyHint(pending.map((m) => m.id))}\n\n${parts}`;
+}
+
+function formatSideChat(pending) {
+  return 'Side chat from the user while you work. Answer now in one short reply each (status, a question, a quick fact), '
+    + 'then carry on with your task exactly where you were; do not stop or change course unless the message asks you to.\n'
+    + `${howToAnswer(pending)}\nReply with:\n${markdownReplyHint(pending.map((m) => m.id))}\n\n${mailLines(pending)}`;
+}
+
+function intro(input, id) {
+  const roots = Array.isArray(input.workspace_roots) ? input.workspace_roots : [];
+  if (!roots.some((r) => String(r).startsWith('/Volumes/docs/My Experiments'))) return null;
+  const marker = path.join(STATE, 'live', `${id}.introduced`);
+  if (fs.existsSync(marker)) return null;
+  fs.mkdirSync(path.dirname(marker), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(marker, String(Date.now()), { mode: 0o600 });
+  return `Agent Hub connected. Your unique bus address is ${id}. Use the always-applied Agent Hub rule for topics and commands. `
+    + `Register your assigned role when convenient. Direct messages from the user arrive between your steps as a side chat: `
+    + `answer them with the reply command and keep working; any left unanswered come back when your turn ends. `
+    + `Other mail includes a reply command and is never auto-captured. Your role and delivery gates do not change. `
+    + `${WRITING_GUIDE} ${CHANNEL_POST_RULE} ${DECISION_RULE}`;
+}
+
+export function handleHook(input, hub) {
+  const event = input.hook_event_name;
+  const id = input.conversation_id;
+  if (!event || !ID.test(String(id || ''))) return {};
+  const { registry, messaging } = hub;
+  registry.ensure(id, { source: 'hook' });
+  registry.heartbeat(id, {
+    event,
+    tool: typeof input.tool_name === 'string' ? input.tool_name.slice(0, 60) : null,
+  });
+
+  if (event === 'afterAgentResponse') {
+    const waiting = messaging.awaiting(id).filter((w) => w.sender === 'user');
+    if (waiting.length && typeof input.text === 'string' && input.text.trim()) {
+      const { reaction, text } = splitReaction(input.text);
+      waiting.forEach((w, i) => {
+        messaging.ack(id, w.id, {
+          reply: i === waiting.length - 1 ? text.slice(0, REPLY_MAX) : null,
+          reaction: i === waiting.length - 1 ? reaction : null,
+        });
+      });
+    }
+    return {};
+  }
+
+  if (event === 'postToolUse' || event === 'postToolUseFailure') {
+    const introduction = intro(input, id);
+    const pending = messaging.peek(id);
+    const others = pending.filter((m) => m.from !== 'user');
+    const fromUser = pending.filter((m) => m.from === 'user');
+    if (others.length) messaging.markDelivered(id, others.map((m) => m.id), { via: 'postToolUse', awaitingReply: false });
+    if (fromUser.length) messaging.markDelivered(id, fromUser.map((m) => m.id), { via: 'side', awaitingReply: false });
+    if (!others.length && !fromUser.length && !introduction) return {};
+    const parts = [introduction];
+    if (fromUser.length) parts.push(formatSideChat(fromUser));
+    if (others.length) parts.push(formatMail(others, { autoCapture: false }));
+    return { additional_context: parts.filter(Boolean).join('\n\n') };
+  }
+
+  if (event === 'stop') {
+    messaging.releaseAwaiting(id);
+    const willRun = (input.status === undefined || input.status === 'completed') && !(Number(input.loop_count) >= STOP_LOOP_LIMIT);
+    if (!willRun) return {};
+    const pending = messaging.peek(id);
+    const unanswered = messaging.sideUnanswered(id);
+    const fromUser = pending.filter((m) => m.from === 'user');
+    const others = pending.filter((m) => m.from !== 'user');
+    if (fromUser.length || unanswered.length) {
+      const claimed = pending.length ? messaging.claim(id, { via: 'stop', limit: pending.length }) : [];
+      const userMail = [...unanswered, ...claimed.filter((m) => m.from === 'user')];
+      messaging.markDelivered(id, userMail.map((m) => m.id), { via: 'stop', awaitingReply: true });
+      const otherMail = claimed.filter((m) => m.from !== 'user');
+      if (otherMail.length) messaging.markDelivered(id, otherMail.map((m) => m.id), { via: 'stop', awaitingReply: false });
+      const parts = [formatMail(userMail, { autoCapture: true })];
+      if (otherMail.length) parts.push(formatMail(otherMail, { autoCapture: false }));
+      return { followup_message: parts.join('\n\n---\n\n') };
+    }
+    // Only mail that asks for an answer is worth a new turn; an FYI reply waits for this chat's next step.
+    const actionable = others.filter((m) => !isFyi(m));
+    if (actionable.length) {
+      const claimed = messaging.claim(id, { via: 'stop', limit: pending.length }).filter((m) => actionable.some((a) => a.id === m.id));
+      messaging.markDelivered(id, claimed.map((m) => m.id), { via: 'stop', awaitingReply: false });
+      if (claimed.length) return { followup_message: formatMail(claimed, { autoCapture: false }) };
+    }
+    return {};
+  }
+  return {};
+}
+
+function main(input) {
+  try {
+    const hub = openHub(STATE);
+    done(handleHook(input, hub));
+  } catch {
+    done();
+  }
+}
+
+const invoked = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (c) => { raw += c; });
+  process.stdin.on('end', () => { try { main(JSON.parse(raw || '{}')); } catch { done(); } });
+  setTimeout(() => done(), 4000).unref();
+}

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