@agentpulselabs/cli-plugin-pulse 1.1.3 → 1.1.6

package/src/runner/facade.js

@@ -23,12 +23,9 @@ import { isBusy } from '../hub/core/ticks.mjs';
 import { handleHook } from '../hub/hooks/hub-bridge.mjs';
 import { defaultDrivers, diagnoseClaude } from '../hub/runners/drivers.mjs';
 import { createRunner } from '../hub/workers/runner.mjs';
-import { readTaskBrief } from '../hub/lib/brief.mjs';
 import { decisionPost, parsePosts } from '../hub/lib/channels.mjs';
 import { STEP_IDS, auditPost, movePost, overrideHolds, overrideKey, overrideText, statusRequest, stepHolds, withOverride, workMoved } from '../hub/lib/status.mjs';
-import { askDetail, channelParticipant, hasChatInbox, listChannels, participantPost, participantThread, postToProject, projectMessages, taskMessages } from '../hub/lib/chat.mjs';
-import { findAgentQuery } from '../hub/lib/transcripts.mjs';
-import { watchTranscripts } from '../hub/lib/transcript-feed.mjs';
+import { channelParticipant, hasChatInbox, participantPost, postToProject } from '../hub/lib/chat.mjs';
 import { HUB, acceptDelivery, keepAwakeStatus, readSettings, validSettings, writeSettings } from '../hub/lib/store.mjs';
 import { createManager } from '../hub/workers/manager.mjs';
 import { NOBODY, aliasesFor } from '../hub/lib/me.mjs';
@@ -37,8 +34,12 @@ import { projectDeliveries } from '../hub/projections/deliveries.mjs';
 import { projectGraph } from '../hub/projections/graph.mjs';
 import { execFileBounded } from '../lib/subprocess.js';
 import { createBusIdentity, routedMessaging } from './busIdentity.js';
+import { channelFileFor as channelFileIn } from './channelFiles.js';
 import { createChannelDiscipline } from './channelDiscipline.js';
 import { createDeliveryStates } from './deliveryStates.js';
+import { createFileReads } from './fileReads.js';
+import { UNMONITORED } from './loopMonitor.js';
+import { serial } from './serial.js';
 import { statusPage } from './statusPage.js';
 
 const WORKSPACE = path.resolve(HUB, '..');
@@ -46,6 +47,8 @@ const CHANNEL_ROOTS = ['AgentPulseApps', 'Google_Cloud'].map((d) => path.join(WO
 const HOURS = [1, 3, 6, 12, 24, 72, 168];
 const CACHE_MS = 4000;
 const CHANGE_DEBOUNCE_MS = 600;
+/** A change feed news of transcripts alone starts a new discovery pass at most this often. */
+const TRANSCRIPT_RESCAN_MS = 15e3;
 /** Steady writes (heartbeats every few hundred ms) keep restarting the debounce; a change still goes out this soon. */
 const CHANGE_MAX_WAIT_MS = 2000;
 /** A graph read re-registers the user at most this often: often enough to stay online, rarely enough not to wake the change feed on every read. */
@@ -64,10 +67,12 @@ const LOCAL_HOST = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
 const LOCAL_ORIGIN = /^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?$/;
 const NO_FRAME = { 'x-frame-options': 'DENY', 'content-security-policy': "frame-ancestors 'none'", 'x-content-type-options': 'nosniff' };
 
-const sendJson = (res, body, code = 200, extra = {}) => {
+/** sendJson for a body already serialized (by the file reads worker): the same headers and bytes. */
+const sendJsonText = (res, text, code = 200, extra = {}) => {
   res.writeHead(code, { 'content-type': 'application/json', 'cache-control': 'no-store', ...NO_FRAME, ...extra });
-  res.end(JSON.stringify(body));
+  res.end(text);
 };
+const sendJson = (res, body, code = 200, extra = {}) => sendJsonText(res, JSON.stringify(body), code, extra);
 
 function trustedWrite(req) {
   const origin = req.headers.origin;
@@ -133,40 +138,11 @@ export function plainCapture(db) {
     tx: (fn, { guard = null, label = 'write' } = {}) => withTx(db, () => { const out = fn(); if (guard) guard(); return out; }, label),
     applying: (fn) => fn(),
     pump: () => 0,
+    chunks: async (steps, { label = 'write' } = {}) => { withTx(db, () => { for (const step of steps) step(); }, label); return 1; },
   };
 }
 
-const BRIEF_CACHE_MS = 30e3;
-const briefCache = new Map();
-
-export function channelFileFor(key, roots = CHANNEL_ROOTS) {
-  const m = String(key || '').match(/^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/);
-  if (!m || m[1].startsWith('.') || m[2].startsWith('.')) return null;
-  for (const root of roots) {
-    const file = path.join(root, m[1], '.agents', m[2], 'channel.md');
-    try {
-      const st = fs.lstatSync(file);
-      if (!st.isFile()) continue;
-      const realRoot = fs.realpathSync(root);
-      if (fs.realpathSync(file) !== path.join(realRoot, m[1], '.agents', m[2], 'channel.md')) continue;
-      return file;
-    } catch { /* not here */ }
-  }
-  return null;
-}
-
-function taskBriefFor(key, roots) {
-  const hit = briefCache.get(key);
-  if (hit && Date.now() - hit.at < BRIEF_CACHE_MS) return hit.body;
-  const file = channelFileFor(key, roots);
-  if (!file) return null;
-  const fromFiles = readTaskBrief(file);
-  const thin = !fromFiles || !fromFiles.sections.some((s) => s.body && s.body.trim());
-  const body = thin ? (readTaskBrief(file, { query: findAgentQuery(key) }) || fromFiles || { title: null, source: null, sections: [] }) : fromFiles;
-  if (briefCache.size > 200) briefCache.clear();
-  briefCache.set(key, { at: Date.now(), body });
-  return body;
-}
+export const channelFileFor = (key, roots = CHANNEL_ROOTS) => channelFileIn(key, roots);
 
 /** How many posts a channel holds now: the position of the one just appended. */
 const postsIn = (file) => parsePosts(fs.readFileSync(file, 'utf8'), Date.now()).length;
@@ -182,14 +158,15 @@ export function appendNoFollow(file, text) {
   } finally { fs.closeSync(fd); }
 }
 
-function collectWorker() {
-  const worker = new Worker(new URL('../hub/lib/collect-worker.mjs', import.meta.url));
+function collectWorker({ onDiscovered = () => {} } = {}) {
+  const worker = new Worker(new URL('./collectWorker.js', import.meta.url));
   const waiting = new Map();
   let seq = 0;
-  worker.on('message', ({ id, body, error }) => {
+  worker.on('message', ({ type, id, text, error }) => {
+    if (type === 'discovered') { onDiscovered(); return; }
     const w = waiting.get(id);
     waiting.delete(id);
-    if (w) { if (error) w.reject(new Error(error)); else w.resolve(body); }
+    if (w) { if (error) w.reject(new Error(error)); else w.resolve(text); }
   });
   worker.on('error', (e) => { console.error(`collector crashed: ${e && e.stack ? e.stack : e}`); process.exit(1); });
   return (hours, managerView, aliases, { discoveryEpoch } = {}) => {
@@ -200,12 +177,23 @@ function collectWorker() {
   };
 }
 
-function collector(run) {
+function collector(run, { rescanMs = TRANSCRIPT_RESCAN_MS } = {}) {
   const cache = new Map();
   /** Bumped by clear() and reproject(): a collect started before a change must not cache its older body. */
   let generation = 0;
   /** Bumped by clear() only: the collector may reuse a discovery pass from the same epoch (workers/collector.mjs). */
   let discoveryEpoch = 0;
+  let epochAt = -Infinity;
+  let rescan = null;
+  const clear = () => {
+    clearTimeout(rescan);
+    rescan = null;
+    generation++;
+    discoveryEpoch++;
+    epochAt = Date.now();
+    cache.clear();
+  };
+  const reproject = () => { generation++; cache.clear(); };
   return {
     graph(hours, managerView, aliases = []) {
       const hit = cache.get(hours);
@@ -218,9 +206,20 @@ function collector(run) {
       cache.set(hours, { ...(hit || {}), running });
       return running;
     },
-    clear() { generation++; discoveryEpoch++; cache.clear(); },
+    clear,
     /** Presence moved and nothing else: refresh the bodies without a new discovery pass. */
-    reproject() { generation++; cache.clear(); },
+    reproject,
+    /**
+     * Only Cursor transcripts moved, which they do every second while agents work: a new discovery pass at most every
+     * `rescanMs`, the last change still picked up by a pass at the end of the wait; reads meanwhile reproject.
+     */
+    transcriptsMoved() {
+      const wait = epochAt + rescanMs - Date.now();
+      if (wait <= 0) return clear();
+      reproject();
+      if (!rescan) { rescan = setTimeout(clear, wait); rescan.unref(); }
+      return undefined;
+    },
   };
 }
 
@@ -231,7 +230,7 @@ function watchRecursive(dir, onFile, onError) {
   return fs.watch(dir, { recursive: true }, (e, f) => { if (f) onFile(String(f)); }).on('error', onError);
 }
 
-function changeFeed(onChange, { stateDir, dbFile, channelRoots, transcriptsDir, hubChanged, watchDir }) {
+function changeFeed(onChange, { stateDir, dbFile, channelRoots, hubChanged, watchDir }) {
   const clients = new Set();
   const pending = new Set();
   let timer = null;
@@ -264,7 +263,6 @@ function changeFeed(onChange, { stateDir, dbFile, channelRoots, transcriptsDir,
   for (const root of channelRoots) watch(root, (f) => (/\.agents[\\/][^\\/]+[\\/](channel|brief)\.md$/.test(f) ? 'channels' : null));
   watch(stateDir, (f) => (/(events\.jsonl|requests|chat[\\/]|inbox[\\/]|bus[\\/]|accepted\.json|personas\.json)/.test(f) ? 'hub' : null));
   if (dbFile) watch(path.dirname(dbFile), (f) => (f.startsWith(dbName) ? DB_WRITE : null));
-  if (transcriptsDir) watchTranscripts(transcriptsDir, () => notify('agents'));
   const keepAlive = setInterval(() => { for (const res of clients) res.write(': keep-alive\n\n'); }, 25e3);
   keepAlive.unref();
   return {
@@ -292,23 +290,53 @@ const hasTable = (db, name) => Boolean(db.prepare("SELECT 1 AS found FROM sqlite
 /** Without a cloud lease (tests, a bare hub) this runner is the only one, as the local hub was. */
 const SOLE_LEASE = Object.freeze({ held: () => true, view: () => ({ holder: 'local', here: true }), onChange: () => {} });
 
+/**
+ * A lease that lapses here only while this process stalled (a long runner.db transaction holds the event loop) comes back
+ * as soon as the queued report is read. The manager pauses meanwhile and is stopped, killing its runs, only past this.
+ */
+export const MANAGER_STOP_GRACE_MS = 60e3;
+const MANAGER_LOG_MAX_BYTES = 1024 * 1024;
+
+/** state/manager.log: what the manager did wrong, with its time, also on stderr; one older file is kept. */
+export function managerLog(file, { echo = console.error } = {}) {
+  return (line) => {
+    echo(line);
+    try {
+      if ((fs.statSync(file, { throwIfNoEntry: false })?.size || 0) > MANAGER_LOG_MAX_BYTES) fs.renameSync(file, `${file}.1`);
+      fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+    } catch { /* stderr has it */ }
+  };
+}
+
 export function serve({
   hub, capture = plainCapture(hub.db), port = 8890, listenHost = '127.0.0.1', stateDir = path.join(HUB, 'state'), dbFile = null,
   enableCollector = true, enableManager = true, collect = null, channelRoots = CHANNEL_ROOTS,
   transcriptsDir = path.join(os.homedir(), '.cursor', 'projects'), watchDir = watchRecursive, identity = null,
   lease = SOLE_LEASE, pulseUrl = null, health = () => ({ state: 'online' }), metrics = () => ({}), drivers = null,
   hookBudgetMs = HOOK_BUDGET_MS, writeBudgetMs = WRITE_BUDGET_MS, onWrite = () => {}, managerOptions = {}, workspaceRoot = WORKSPACE,
-  discipline: disciplineOptions = {},
+  discipline: disciplineOptions = {}, loop = UNMONITORED,
 } = {}) {
   const me = () => {
     const m = identity ? identity.current() : NOBODY;
     return m === NOBODY ? NOBODY : { ...m, aliases: aliasesFor(m, personaUsernames()) };
   };
-  const graphs = enableCollector ? collector(collect || collectWorker()) : { graph: async () => ({ nodes: [], links: [], events: [], deliveries: [], agents: [], totals: {} }), clear() {}, reproject() {} };
+  // A discovery pass the worker saved after answering: later reads project its rows, and change-feed clients read again.
+  const graphs = enableCollector ? collector(collect || collectWorker({ onDiscovered: () => { graphs.reproject(); feed.notify('presence'); } })) : { graph: async () => ({ nodes: [], links: [], events: [], deliveries: [], agents: [], totals: {} }), clear() {}, reproject() {}, transcriptsMoved() {} };
   const caches = { clear: () => graphs.clear() };
+  const onFeedChange = (kinds) => {
+    if (kinds.every((k) => k === 'presence')) return graphs.reproject();
+    if (kinds.every((k) => k === 'presence' || k === 'agents')) return graphs.transcriptsMoved();
+    return graphs.clear();
+  };
   const feed = enableCollector
-    ? changeFeed((kinds) => (kinds.every((k) => k === 'presence') ? graphs.reproject() : graphs.clear()), { stateDir, dbFile, channelRoots, transcriptsDir, hubChanged: changeTracker(hub.db), watchDir })
+    ? changeFeed(onFeedChange, { stateDir, dbFile, channelRoots, hubChanged: changeTracker(hub.db), watchDir })
     : { attach(req, res) { res.writeHead(200); res.end(); }, dbWrite() {}, notify() {}, close() {} };
+  // Channel, brief and transcript files are read and parsed off the event loop (fileReadsWorker.js).
+  const fileReads = createFileReads({ roots: channelRoots, transcriptsDir: enableCollector ? transcriptsDir : null, onTranscripts: () => feed.notify('agents') });
+  /** Answers a route from the file reads worker; `fallback` answers what the worker leaves to the hub (null). */
+  const fromFiles = (res, op, args, fallback = null) => fileReads.read(op, args, { text: true })
+    .then((answer) => (answer ? sendJsonText(res, ...answer) : fallback()))
+    .catch((e) => { console.error(`file read failed: ${op}: ${e.message}`); if (!res.headersSent) sendJson(res, { error: 'server error' }, 500); });
   if (identity) {
     identity.listen(() => { graphs.clear(); feed.notify('hub'); });
     identity.refresh();
@@ -320,8 +348,9 @@ export function serve({
     channelRoots, workspaceRoot, append: appendNoFollow, ...thresholds,
     publish: (message) => hub.messaging.publish(message, hub.registry.directory()),
   });
+  const logManager = managerOptions.log || managerLog(path.join(stateDir, 'manager.log'));
   const manager = enableManager
-    ? createManager({ hub, state: stateDir, onChange: () => graphs.clear(), held: () => lease.held(), fyi: (m) => delivery.managerFyi(m), ...managerOptions })
+    ? createManager({ hub, state: stateDir, onChange: () => graphs.clear(), held: () => lease.held(), fyi: (m) => delivery.managerFyi(m), ...managerOptions, log: logManager })
     : { start() {}, stop() {}, view() { return { state: 'offline', online: false, pending: 0 }; } };
   /** The manager's status, with the DONE and STATUS posts it has read (F2). */
   const managerView = () => ({ ...manager.view(), reports: delivery.reports() });
@@ -334,30 +363,65 @@ export function serve({
   }
   if (serverLease.error) console.error(`another hub server holds the lease (${serverLease.holder}); taking over`);
   const timers = [];
-  const every = (ms, fn) => { const t = setInterval(fn, ms); t.unref(); timers.push(t); };
+  const every = (ms, fn, name = 'timer') => { const t = setInterval(() => loop.tick(name, fn), ms); t.unref(); timers.push(t); };
   if (serverLease.token) {
-    every(10e3, () => { try { hub.leases.renew('server', serverLease.token, { ttlMs: 30e3 }); } catch (e) { console.error(`server lease renewal failed: ${e.message}`); } });
+    every(10e3, () => { try { hub.leases.renew('server', serverLease.token, { ttlMs: 30e3 }); } catch (e) { console.error(`server lease renewal failed: ${e.message}`); } }, 'server lease');
   }
   const releaseLease = () => { if (serverLease.token) { try { hub.leases.release('server', serverLease.token); } catch { /* closing */ } } };
   const wrote = () => { feed.dbWrite(); onWrite(); };
   /** The manager, the wake sweep and the scheduled nudge belong to the runner holding the user's manager lease (Q9). */
   const leaseHeld = () => lease.held();
+  const deliverySweep = serial(async () => {
+    try {
+      const settled = capture.tx(() => delivery.settleNudges(), { label: 'delivery sweep' });
+      const bounced = [];
+      await capture.chunks(delivery.bounceSteps({ sent: bounced }), { label: 'delivery bounce' });
+      if (settled + bounced.length) { caches.clear(); wrote(); }
+    } catch (e) { console.error(`delivery sweep failed: ${e.message}`); }
+  });
+  const staleSweep = serial(async () => {
+    try {
+      const seen = await discipline.scan();
+      if (leaseHeld() && capture.tx(() => discipline.sweep({ seen }).length, { label: 'stale sweep' })) { caches.clear(); wrote(); }
+    } catch (e) { console.error(`stale sweep failed: ${e.message}`); }
+  });
   if (enableManager) {
     if (leaseHeld()) manager.start();
-    lease.onChange((held) => { if (held) manager.start(); else manager.stop(); });
+    let lapsedAt = null;
+    let stopTimer = null;
+    lease.onChange((held) => {
+      const { fence } = lease.view();
+      if (held) {
+        clearTimeout(stopTimer);
+        stopTimer = null;
+        if (lapsedAt) {
+          logManager(`manager lease held again (fence ${fence})${fence !== lapsedAt.fence ? `; it moved from fence ${lapsedAt.fence}, so runs from before are stopped` : ''}`);
+          if (fence !== lapsedAt.fence) manager.stop();
+        }
+        lapsedAt = null;
+        manager.start();
+        return;
+      }
+      if (lapsedAt) return;
+      lapsedAt = { fence };
+      logManager(`manager lease lapsed here (fence ${fence}); runs in flight keep going, and are stopped if it is not back in ${MANAGER_STOP_GRACE_MS / 1000} s`);
+      stopTimer = setTimeout(() => {
+        stopTimer = null;
+        if (lease.held()) return;
+        logManager('manager lease still not held: the manager is stopped');
+        manager.stop();
+      }, MANAGER_STOP_GRACE_MS);
+      stopTimer.unref();
+    });
     every(60e3, () => {
       if (!leaseHeld()) return;
       try { if (capture.tx(() => sweepWakes(hub), { label: 'wake sweep' }).length) { caches.clear(); wrote(); } } catch (e) { console.error(`wake sweep failed: ${e.message}`); }
-      try {
-        if (capture.tx(() => delivery.settleNudges() + delivery.bounce().length, { label: 'delivery sweep' })) { caches.clear(); wrote(); }
-      } catch (e) { console.error(`delivery sweep failed: ${e.message}`); }
-    });
+      return deliverySweep();
+    }, 'wake and delivery sweep');
     every(disciplineSweepMs, () => {
       if (!leaseHeld()) return;
-      try {
-        if (capture.tx(() => discipline.sweep().length, { label: 'stale sweep' })) { caches.clear(); wrote(); }
-      } catch (e) { console.error(`stale sweep failed: ${e.message}`); }
-    });
+      return staleSweep();
+    }, 'stale sweep');
   }
   const runner = createRunner({ hub, drivers: drivers || defaultDrivers(), workspaceRoot: WORKSPACE, onChange: () => { graphs.clear(); wrote(); } });
   if (enableManager) runner.begin();
@@ -369,7 +433,7 @@ export function serve({
       });
       if (capture.tx(nudge, { label: 'scheduled nudge' })) { caches.clear(); wrote(); }
     } catch (e) { console.error(`scheduled nudge failed: ${e.message}`); }
-  });
+  }, 'scheduled nudge');
 
   const registeredAt = hasTable(hub.db, 'pulse_registered')
     ? hub.db.prepare('INSERT INTO pulse_registered (id, at) VALUES (?, ?) ON CONFLICT (id) DO UPDATE SET at = excluded.at')
@@ -469,7 +533,12 @@ export function serve({
         capture.tx(() => hub.registry.register({ id: 'user', role: 'USER', name: 'You', topics: ['user'], node_type: 'user' }), { label: 'graph user' });
         wrote();
       }
-      return graphs.graph(hours, managerView(), me().aliases).then((body) => sendJson(res, { ...body, settings: { ...settingsOf(hub), me: me() } }))
+      return graphs.graph(hours, managerView(), me().aliases).then((body) => {
+        const settings = { ...settingsOf(hub), me: me() };
+        // The collect worker answers JSON text of an object without `settings`; appended last, the bytes are those of the spread.
+        if (typeof body === 'string' && body.length > 2 && body.endsWith('}')) return sendJsonText(res, `${body.slice(0, -1)},"settings":${JSON.stringify(settings)}}`);
+        return sendJson(res, { ...(typeof body === 'string' ? JSON.parse(body) : body), settings });
+      })
         .catch((e) => { console.error(`collect failed: ${e.message}`); if (!res.headersSent) sendJson(res, { error: 'server error' }, 500); });
     }
     if (p === '/api/settings' && req.method === 'GET') return sendJson(res, { ...settingsOf(hub), me: me() });
@@ -495,8 +564,7 @@ export function serve({
     if (p === '/api/task/brief' && req.method === 'GET') {
       const key = String(url.searchParams.get('key') || '');
       if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(key)) return sendJson(res, { error: 'no such channel' }, 404);
-      const brief = taskBriefFor(key, channelRoots);
-      return brief ? sendJson(res, brief) : sendJson(res, { error: 'no such channel' }, 404);
+      return fromFiles(res, 'brief', { key });
     }
     if (p === '/api/runs' && req.method === 'GET') return sendJson(res, { runs: runner.list(), drivers: runner.drivers() });
     if (p === '/api/runs/diagnose' && req.method === 'GET') {
@@ -505,12 +573,10 @@ export function serve({
     }
     if (p === '/api/task/ask' && req.method === 'GET') {
       const key = String(url.searchParams.get('key') || '');
-      const file = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(key) ? channelFileFor(key, channelRoots) : null;
-      if (!file) return sendJson(res, { error: 'no such channel' }, 404);
+      if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(key)) return sendJson(res, { error: 'no such channel' }, 404);
       const ref = String(url.searchParams.get('ref') || '');
       const at = Number(url.searchParams.get('at')) || null;
-      const detail = askDetail(file, { ref: /^[A-Z]?\d+$/.test(ref) ? ref : null, at, aliases: me().aliases });
-      return detail ? sendJson(res, detail) : sendJson(res, { error: 'no open ask in this channel' }, 404);
+      return fromFiles(res, 'ask', { key, ref: /^[A-Z]?\d+$/.test(ref) ? ref : null, at, aliases: me().aliases });
     }
     if (p === '/api/inbox' && req.method === 'GET') {
       const since = Math.max(Date.now() - 24 * 3600e3, Number(url.searchParams.get('since')) || 0);
@@ -520,29 +586,16 @@ export function serve({
       return sendJson(res, { messages, at: Date.now() });
     }
     if (p === '/api/chat/channels' && req.method === 'GET') {
-      const dms = hub.conversations.dmPartners();
-      return sendJson(res, { ...listChannels(channelRoots, Date.now() - CHAT_CHANNELS_MS), dms });
+      return fileReads.read('channels', { sinceMs: Date.now() - CHAT_CHANNELS_MS })
+        .then(([listed]) => sendJson(res, { ...listed, dms: hub.conversations.dmPartners() }))
+        .catch((e) => { console.error(`file read failed: channels: ${e.message}`); if (!res.headersSent) sendJson(res, { error: 'server error' }, 500); });
     }
     if (p === '/api/chat/messages' && req.method === 'GET') {
       const ch = String(url.searchParams.get('ch') || '');
-      if (ch.startsWith('task:')) {
-        const file = channelFileFor(ch.slice(5), channelRoots);
-        return file ? sendJson(res, { messages: taskMessages(file) }) : sendJson(res, { error: 'no such channel' }, 404);
-      }
-      if (ch.startsWith('project:')) {
-        const messages = projectMessages(channelRoots, ch.slice(8), Date.now() - CHAT_HISTORY_MS);
-        return messages ? sendJson(res, { messages }) : sendJson(res, { error: 'no such channel' }, 404);
-      }
-      if (ch.startsWith('dm:')) {
-        const part = channelParticipant(ch.slice(3));
-        if (part) {
-          const file = channelFileFor(part.key, channelRoots);
-          return file ? sendJson(res, { messages: participantThread(file, part.role) }) : sendJson(res, { error: 'no such person' }, 404);
-        }
+      return fromFiles(res, 'messages', { ch, historyMs: CHAT_HISTORY_MS }, () => {
         const dm = hub.conversations.thread(ch.slice(3));
         return dm ? sendJson(res, dm) : sendJson(res, { error: 'no such person' }, 404);
-      }
-      return sendJson(res, { error: 'no such channel' }, 404);
+      });
     }
     if (p === '/api/deliveries' && req.method === 'GET') return sendJson(res, projectDeliveries(hub));
     if (p === '/api/legacy/map' && req.method === 'GET') {
@@ -579,9 +632,17 @@ export function serve({
         const pollStarted = Date.now();
         let beat = pollStarted;
         const inbox = routedMessaging(hub.messaging, box.addresses);
+        const claimsFor = box.addresses.length > 1 && box.addresses[0] === bound.principal ? box.addresses : [bound.principal];
         // Re-polls run from a timer, outside readBody's try/catch: a busy database waits for the next poll, anything else answers 503.
         const poll = () => {
           if (!connected(req, res)) return undefined;
+          let idle = false;
+          try { idle = !(body.heartbeat === true && Date.now() - beat >= LISTEN_HEARTBEAT_MS) && !bus.claimable(claimsFor); } catch { /* the claim below says why */ }
+          if (idle) {
+            if (Date.now() - pollStarted >= timeout) return sendJson(res, { messages: [], at: Date.now() });
+            setTimeout(poll, 250).unref();
+            return undefined;
+          }
           let messages = [];
           try {
             messages = commit(req, res, pollStarted, Infinity, () => {
@@ -867,6 +928,7 @@ export function serve({
   });
   server.on('close', () => {
     feed.close();
+    fileReads.close();
     for (const t of timers) clearInterval(t);
     manager.stop();
     releaseLease();

package/src/runner/fileReads.js

@@ -0,0 +1,64 @@
+import { Worker } from 'node:worker_threads';
+
+/** A worker that died is started again after this long, so a crash can't turn into a busy loop. */
+const RESTART_MS = 1000;
+
+/**
+ * The facade's side of fileReadsWorker.js. `read(op, args)` resolves to the route's [body, status], or null for a
+ * `dm:` that is the hub's own thread; with `{ text: true }` the body comes as its JSON text. The worker also runs the transcript feed when given `transcriptsDir`, calling
+ * `onTranscripts` once per pass that saw a transcript move. A worker that dies fails the reads it had in flight and is
+ * started again; `close()` stops it.
+ */
+export function createFileReads({ roots, transcriptsDir = null, onTranscripts = () => {} }) {
+  const waiting = new Map();
+  let seq = 0;
+  let worker = null;
+  let closed = false;
+  let restart = null;
+
+  const start = () => {
+    const w = new Worker(new URL('./fileReadsWorker.js', import.meta.url), { workerData: { roots, transcriptsDir } });
+    w.unref();
+    w.on('message', (m) => {
+      if (m.type === 'agents') { onTranscripts(); return; }
+      const pending = waiting.get(m.id);
+      if (!pending) return;
+      waiting.delete(m.id);
+      if (m.error) pending.reject(new Error(m.error)); else pending.resolve(m.answer);
+    });
+    const failed = (error) => {
+      if (worker !== w) return;
+      worker = null;
+      for (const pending of waiting.values()) pending.reject(error);
+      waiting.clear();
+      if (transcriptsDir && !closed && !restart) {
+        restart = setTimeout(() => { restart = null; if (!closed && !worker) worker = start(); }, RESTART_MS);
+        restart.unref();
+      }
+    };
+    w.on('error', (e) => { console.error(`file reads worker failed: ${e && e.stack ? e.stack : e}`); failed(e); });
+    w.on('exit', (code) => failed(new Error(`the file reads worker exited (${code})`)));
+    return w;
+  };
+  if (transcriptsDir) worker = start();
+
+  return {
+    read(op, args, { text = false } = {}) {
+      if (closed) return Promise.reject(new Error('the file reads worker is closed'));
+      worker ??= start();
+      const id = ++seq;
+      const answer = new Promise((resolve, reject) => waiting.set(id, { resolve, reject }));
+      worker.postMessage({ id, op, args, text });
+      return answer;
+    },
+    close() {
+      closed = true;
+      clearTimeout(restart);
+      const w = worker;
+      worker = null;
+      for (const pending of waiting.values()) pending.reject(new Error('the file reads worker is closed'));
+      waiting.clear();
+      if (w) w.terminate();
+    },
+  };
+}

package/src/runner/fileReadsWorker.js

@@ -0,0 +1,61 @@
+// The facade's file reads, off the runner's event loop: channel and brief files and Cursor transcripts are read and
+// parsed here with the same hub functions the routes called inline, so each answer is the same, byte for byte.
+import { parentPort, workerData } from 'node:worker_threads';
+import { askDetail, channelParticipant, listChannels, participantThread, projectMessages, taskMessages } from '../hub/lib/chat.mjs';
+import { channelFileFor, taskBriefFor } from './channelFiles.js';
+import { watchTranscripts } from './transcriptFeed.js';
+
+const { roots, transcriptsDir } = workerData;
+const NOT_FOUND = (error) => [{ error }, 404];
+
+/** Each op answers [body, status]; a dm: that isn't a channel participant is the hub's own (null: the caller reads it). */
+const OPS = {
+  brief: ({ key }) => {
+    const brief = taskBriefFor(key, roots);
+    return brief ? [brief, 200] : NOT_FOUND('no such channel');
+  },
+  ask: ({ key, ref, at, aliases }) => {
+    const file = channelFileFor(key, roots);
+    if (!file) return NOT_FOUND('no such channel');
+    const detail = askDetail(file, { ref, at, aliases });
+    return detail ? [detail, 200] : NOT_FOUND('no open ask in this channel');
+  },
+  channels: ({ sinceMs }) => [listChannels(roots, sinceMs), 200],
+  messages: ({ ch, historyMs }) => {
+    if (ch.startsWith('task:')) {
+      const file = channelFileFor(ch.slice(5), roots);
+      return file ? [{ messages: taskMessages(file) }, 200] : NOT_FOUND('no such channel');
+    }
+    if (ch.startsWith('project:')) {
+      const messages = projectMessages(roots, ch.slice(8), Date.now() - historyMs);
+      return messages ? [{ messages }, 200] : NOT_FOUND('no such channel');
+    }
+    if (ch.startsWith('dm:')) {
+      const part = channelParticipant(ch.slice(3));
+      if (!part) return null;
+      const file = channelFileFor(part.key, roots);
+      return file ? [{ messages: participantThread(file, part.role) }, 200] : NOT_FOUND('no such person');
+    }
+    return NOT_FOUND('no such channel');
+  },
+};
+
+parentPort.on('message', ({ id, op, args, text = false }) => {
+  try {
+    const answer = OPS[op](args);
+    // As JSON text the answer crosses to the main thread as one string, not an object graph it must clone and stringify.
+    parentPort.postMessage({ id, answer: text && answer ? [JSON.stringify(answer[0]), answer[1]] : answer });
+  } catch (e) {
+    parentPort.postMessage({ id, error: String((e && e.stack) || e) });
+  }
+});
+
+if (transcriptsDir) {
+  // One message per pass of the feed, however many transcript files it saw move.
+  let queued = false;
+  watchTranscripts(transcriptsDir, () => {
+    if (queued) return;
+    queued = true;
+    queueMicrotask(() => { queued = false; parentPort.postMessage({ type: 'agents' }); });
+  });
+}