@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/hub/core/registry.mjs

@@ -0,0 +1,281 @@
+// agents-hub core/registry.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Actors, presence, and topic → recipients. A registered identity always outranks an inferred one.
+import { ADDRESS, NODE_TYPES, ONLINE_MS, SOURCE_RANK, TOPIC, displayTitle, nodeTypeOf } from './ids.mjs';
+import { jsonCol, parseJson, withTx } from './db.mjs';
+
+export { displayTitle, nodeTypeOf };
+
+function rowActor(r) {
+  if (!r) return null;
+  return {
+    id: r.id,
+    node_type: r.node_type,
+    role: r.role,
+    parent_id: r.parent_id,
+    delivery_id: r.delivery_id,
+    stream_key: r.stream_key,
+    cursor_title: r.cursor_title,
+    prompt_title: r.prompt_title,
+    persona_name: r.persona_name,
+    persona_first: r.persona_first,
+    persona_username: r.persona_username,
+    persona_seed: r.persona_seed,
+    persona: parseJson(r.persona_json, null),
+    source: r.source,
+    topics: parseJson(r.topics, []),
+    started_at: r.started_at,
+    last_at: r.last_at,
+    tokens_est: r.tokens_est,
+    msgs_in: r.msgs_in,
+    msgs_out: r.msgs_out,
+    repo: r.repo,
+    channel: r.channel,
+    synthetic: !!r.synthetic,
+    extra: parseJson(r.extra, null),
+    title: displayTitle(r),
+  };
+}
+
+export function createRegistry(db) {
+  const getStmt = db.prepare('SELECT * FROM actors WHERE id = ?');
+  const allStmt = db.prepare('SELECT * FROM actors');
+  const presenceStmt = db.prepare('SELECT * FROM presence WHERE actor_id = ?');
+  const allPresenceStmt = db.prepare('SELECT * FROM presence');
+
+  function get(id) { return rowActor(getStmt.get(id)); }
+
+  function all() { return allStmt.all().map(rowActor); }
+
+  function ensure(id, defaults = {}) {
+    const existing = getStmt.get(id);
+    if (existing) return rowActor(existing);
+    const nodeType = defaults.node_type || nodeTypeOf({ id, parentId: defaults.parent_id, synthetic: defaults.synthetic, role: defaults.role });
+    db.prepare(`INSERT OR IGNORE INTO actors (id, node_type, source, role, parent_id) VALUES (?, ?, ?, ?, ?)`)
+      .run(id, nodeType, defaults.source || 'hook', defaults.role || null, defaults.parent_id || null);
+    return get(id);
+  }
+
+  function register({ id, role = null, name = null, topics = [], parent = null, node_type = null }) {
+    if (!ADDRESS.test(String(id || ''))) return { error: 'bad address' };
+    const cleanTopics = [...new Set((Array.isArray(topics) ? topics : []).filter((t) => TOPIC.test(t)))].slice(0, 30);
+    const now = Date.now();
+    return withTx(db, () => {
+      const prior = getStmt.get(id);
+      const nextParent = ADDRESS.test(String(parent || '')) ? parent : (prior && prior.parent_id);
+      const nodeType = node_type || nodeTypeOf({
+        id, parentId: nextParent, role: role || (prior && prior.role), synthetic: prior && prior.synthetic,
+      });
+      if (!NODE_TYPES.includes(nodeType)) return { error: 'bad node_type' };
+      if (!prior) {
+        db.prepare(`INSERT INTO actors (id, node_type, role, parent_id, source, topics, persona_name, last_at)
+          VALUES (?, ?, ?, ?, 'registered', ?, ?, ?)`)
+          .run(id, nodeType,
+            typeof role === 'string' && role ? role.toUpperCase().slice(0, 30) : null,
+            ADDRESS.test(String(parent || '')) ? parent : null,
+            jsonCol(cleanTopics),
+            typeof name === 'string' && name ? name.slice(0, 80) : null,
+            now);
+      } else {
+        const nextRole = typeof role === 'string' && role ? role.toUpperCase().slice(0, 30) : prior.role;
+        const nextTopics = cleanTopics.length ? cleanTopics : parseJson(prior.topics, []);
+        const nextName = typeof name === 'string' && name ? name.slice(0, 80) : prior.persona_name;
+        db.prepare(`UPDATE actors SET node_type = ?, role = ?, parent_id = ?, source = 'registered', topics = ?,
+          persona_name = COALESCE(?, persona_name), last_at = ? WHERE id = ?`)
+          .run(nodeType, nextRole, nextParent, jsonCol(nextTopics), nextName, now, id);
+      }
+      heartbeat(id, { event: 'register' });
+      const row = get(id);
+      return { ...row, online: true, seenAt: now, pending: 0 };
+    }, 'register');
+  }
+
+  /**
+   * Discovery write. Never demotes a registered identity. Presence is a separate table so a heartbeat cannot
+   * rewrite who an agent is.
+   */
+  function upsertInferred(patch) {
+    const id = String(patch.id || '');
+    if (!id || id.length > 200) return { error: 'bad id' };
+    const source = patch.source || 'transcript';
+    const rank = SOURCE_RANK[source] || 0;
+    return withTx(db, () => {
+      const prior = getStmt.get(id);
+      const priorRank = prior ? (SOURCE_RANK[prior.source] || 0) : 0;
+      const parentId = patch.parent_id || (prior && prior.parent_id) || null;
+      const nodeType = nodeTypeOf({
+        id, parentId, synthetic: patch.synthetic || (prior && prior.synthetic),
+        role: patch.role || (prior && prior.role),
+      });
+      if (!prior) {
+        db.prepare(`INSERT INTO actors (id, node_type, role, parent_id, delivery_id, stream_key, cursor_title, prompt_title,
+          persona_name, persona_first, persona_username, persona_seed, persona_json, source, topics, started_at, last_at,
+          tokens_est, msgs_in, msgs_out, repo, channel, synthetic, extra)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+          .run(id, nodeType, patch.role || null, patch.parent_id || null, patch.delivery_id || null, patch.stream_key || null,
+            patch.cursor_title || null, patch.prompt_title || null, patch.persona_name || null, patch.persona_first || null,
+            patch.persona_username || null, patch.persona_seed ?? null, jsonCol(patch.persona || patch.persona_json),
+            source, jsonCol(patch.topics || []), patch.started_at || null, patch.last_at || null,
+            patch.tokens_est ?? null, patch.msgs_in || 0, patch.msgs_out || 0, patch.repo || null, patch.channel || null,
+            patch.synthetic ? 1 : 0, jsonCol(patch.extra || null));
+        return get(id);
+      }
+      if (rank < priorRank) {
+        // A registered or hook-seen actor keeps what it said about itself (role, names, topics); discovery still owns
+        // the facts only it can know: streams and status (extra), repo, channel, start time.
+        db.prepare(`UPDATE actors SET
+          node_type = ?, role = COALESCE(role, ?), parent_id = COALESCE(parent_id, ?), delivery_id = COALESCE(delivery_id, ?),
+          stream_key = COALESCE(?, stream_key), cursor_title = COALESCE(cursor_title, ?),
+          prompt_title = COALESCE(prompt_title, ?), persona_name = COALESCE(persona_name, ?),
+          persona_first = COALESCE(persona_first, ?), persona_username = COALESCE(persona_username, ?),
+          persona_seed = COALESCE(persona_seed, ?), persona_json = COALESCE(persona_json, ?),
+          started_at = COALESCE(started_at, ?), last_at = MAX(COALESCE(last_at, 0), COALESCE(?, 0)), tokens_est = COALESCE(?, tokens_est),
+          msgs_in = COALESCE(?, msgs_in), msgs_out = COALESCE(?, msgs_out),
+          repo = COALESCE(?, repo), channel = COALESCE(?, channel), extra = COALESCE(?, extra)
+          WHERE id = ?`)
+          .run(nodeType, patch.role || null, patch.parent_id || null, patch.delivery_id || null, patch.stream_key || null,
+            patch.cursor_title || null, patch.prompt_title || null, patch.persona_name || null,
+            patch.persona_first || null, patch.persona_username || null, patch.persona_seed ?? null, jsonCol(patch.persona || patch.persona_json),
+            patch.started_at || null, patch.last_at ?? null, patch.tokens_est ?? null, patch.msgs_in ?? null, patch.msgs_out ?? null,
+            patch.repo || null, patch.channel || null, jsonCol(patch.extra || null), id);
+        return get(id);
+      }
+      db.prepare(`UPDATE actors SET
+        node_type = ?, role = COALESCE(?, role), parent_id = COALESCE(?, parent_id),
+        delivery_id = COALESCE(?, delivery_id), stream_key = COALESCE(?, stream_key),
+        cursor_title = COALESCE(?, cursor_title), prompt_title = COALESCE(?, prompt_title),
+        persona_name = COALESCE(?, persona_name), persona_first = COALESCE(?, persona_first),
+        persona_username = COALESCE(?, persona_username), persona_seed = COALESCE(?, persona_seed),
+        persona_json = COALESCE(?, persona_json), source = ?,
+        started_at = COALESCE(started_at, ?), last_at = COALESCE(?, last_at),
+        tokens_est = COALESCE(?, tokens_est), msgs_in = COALESCE(?, msgs_in), msgs_out = COALESCE(?, msgs_out),
+        repo = COALESCE(?, repo), channel = COALESCE(?, channel), synthetic = ?, extra = COALESCE(?, extra)
+        WHERE id = ?`)
+        .run(nodeType, patch.role || null, patch.parent_id || null, patch.delivery_id || null, patch.stream_key || null,
+          patch.cursor_title || null, patch.prompt_title || null, patch.persona_name || null, patch.persona_first || null,
+          patch.persona_username || null, patch.persona_seed ?? null, jsonCol(patch.persona || patch.persona_json),
+          rank >= priorRank ? source : prior.source, patch.started_at || null, patch.last_at || null,
+          patch.tokens_est ?? null, patch.msgs_in ?? null, patch.msgs_out ?? null, patch.repo || null, patch.channel || null,
+          patch.synthetic ? 1 : (prior.synthetic || 0), jsonCol(patch.extra || null), id);
+      return get(id);
+    }, 'upsertInferred');
+  }
+
+  function heartbeat(id, { event = null, tool = null, at = Date.now() } = {}) {
+    if (!id) return;
+    ensure(id, { source: 'hook' });
+    db.prepare(`INSERT INTO presence (actor_id, last_seen, last_event, last_tool) VALUES (?, ?, ?, ?)
+      ON CONFLICT(actor_id) DO UPDATE SET
+        last_seen = MAX(presence.last_seen, excluded.last_seen),
+        last_event = CASE WHEN excluded.last_seen >= presence.last_seen THEN excluded.last_event ELSE presence.last_event END,
+        last_tool = CASE WHEN excluded.last_seen >= presence.last_seen THEN excluded.last_tool ELSE presence.last_tool END`)
+      .run(id, at, event, tool);
+    db.prepare('UPDATE actors SET last_at = MAX(COALESCE(last_at, 0), ?) WHERE id = ?').run(at, id);
+  }
+
+  function presence(id) { return presenceStmt.get(id) || null; }
+
+  function presences() {
+    const map = new Map();
+    for (const p of allPresenceStmt.all()) map.set(p.actor_id, p);
+    return map;
+  }
+
+  function directory(now = Date.now()) {
+    const live = presences();
+    return all().map((a) => {
+      const p = live.get(a.id);
+      const seenAt = p ? p.last_seen : (a.last_at || 0);
+      const online = !!(p && now - p.last_seen < ONLINE_MS);
+      const status = online ? 'working' : ((a.extra && a.extra.status) || 'done');
+      return {
+        ...a,
+        id: a.id,
+        role: a.role,
+        streamKey: a.stream_key,
+        deliveryId: a.delivery_id || (a.node_type === 'orchestrator' ? a.id : a.parent_id) || null,
+        parent: a.parent_id,
+        isArchitect: a.node_type === 'orchestrator',
+        status,
+        topics: a.topics || [],
+        online: !!(p && now - p.last_seen < ONLINE_MS),
+        seenAt,
+        streams: parseJson(a.extra && a.extra.streams, a.extra && Array.isArray(a.extra.streams) ? a.extra.streams : []),
+      };
+    });
+  }
+
+  function registrations(now = Date.now()) {
+    return directory(now).filter((a) => a.source === 'registered' || a.online || a.id === 'user' || a.id === 'manager')
+      .map((a) => ({ id: a.id, role: a.role, name: a.persona_name, topics: a.topics, parent: a.parent_id, seenAt: a.seenAt, online: a.online }));
+  }
+
+  /**
+   * The agents a topic reaches. Finished (not online, status done) agents are skipped for group topics, still
+   * addressable directly via agent/<id>.
+   */
+  function resolveTopic(topic, from, now = Date.now()) {
+    if (!TOPIC.test(String(topic || ''))) return [];
+    const dir = directory(now);
+    const live = dir.filter((a) => a.status !== 'done' && ADDRESS.test(a.id));
+    let ids = [];
+    if (topic === 'manager' || topic === 'agent/manager') ids = ['manager'];
+    else if (topic === 'user' || topic === 'agent/user') ids = ['user'];
+    else if (topic.startsWith('agent/')) ids = [topic.slice(6)];
+    else if (topic.startsWith('stream/')) {
+      const key = topic.slice(7);
+      const crew = live.filter((a) => a.streamKey === key);
+      const owner = dir.find((a) => a.isArchitect && (a.streams || []).includes(key));
+      ids = [...crew.map((a) => a.id), ...(owner ? [owner.id] : [])];
+    } else if (topic.startsWith('delivery/')) {
+      const id = topic.slice(9);
+      ids = dir.filter((a) => a.isArchitect && a.deliveryId === id).map((a) => a.id);
+    } else if (topic.startsWith('role/')) {
+      const role = topic.slice(5);
+      ids = live.filter((a) => (role === 'ARCHITECT' ? a.isArchitect : a.role === role)).map((a) => a.id);
+    } else if (topic === 'broadcast') ids = live.map((a) => a.id);
+    ids.push(...live.filter((a) => Array.isArray(a.topics) && a.topics.includes(topic)).map((a) => a.id));
+    return [...new Set(ids)].filter((id) => id !== from && ADDRESS.test(id));
+  }
+
+  function setFact(kind, key, payload) {
+    db.prepare(`INSERT INTO facts (kind, key, payload, updated_at) VALUES (?, ?, ?, ?)
+      ON CONFLICT(kind, key) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`)
+      .run(kind, key, jsonCol(payload), Date.now());
+  }
+
+  function dropFact(kind, key) {
+    db.prepare('DELETE FROM facts WHERE kind = ? AND key = ?').run(kind, key);
+  }
+
+  /** Drop every fact of a kind whose key is not in `keys` (a discovery pass replaces what it owns). */
+  function keepFacts(kind, keys) {
+    const keep = new Set(keys);
+    const del = db.prepare('DELETE FROM facts WHERE kind = ? AND key = ?');
+    for (const r of db.prepare('SELECT key FROM facts WHERE kind = ?').all(kind)) if (!keep.has(r.key)) del.run(kind, r.key);
+  }
+
+  function fact(kind, key) {
+    const row = db.prepare('SELECT payload FROM facts WHERE kind = ? AND key = ?').get(kind, key);
+    return row ? parseJson(row.payload, null) : null;
+  }
+
+  function facts(kind) {
+    return db.prepare('SELECT key, payload, updated_at FROM facts WHERE kind = ?').all(kind)
+      .map((r) => ({ key: r.key, ...parseJson(r.payload, {}), updated_at: r.updated_at }));
+  }
+
+  function appendEvent({ at = Date.now(), kind, actor = null, payload = {} }) {
+    db.prepare('INSERT INTO events (at, kind, actor, payload) VALUES (?, ?, ?, ?)').run(at, kind, actor, jsonCol(payload));
+  }
+
+  function eventsSince(sinceMs = 0, limit = 400) {
+    return db.prepare('SELECT * FROM events WHERE at >= ? ORDER BY at DESC LIMIT ?').all(sinceMs, limit)
+      .map((e) => ({ id: e.id, at: e.at, kind: e.kind, actor: e.actor, ...parseJson(e.payload, {}) }))
+      .reverse();
+  }
+
+  return {
+    get, all, ensure, register, upsertInferred, heartbeat, presence, presences, directory,
+    registrations, resolveTopic, setFact, dropFact, keepFacts, fact, facts, appendEvent, eventsSince, displayTitle,
+  };
+}

package/src/hub/core/ticks.mjs

@@ -0,0 +1,58 @@
+// agents-hub core/ticks.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Worker ticks run from timers, where an uncaught error ends the hub. A guarded tick logs, backs off and carries on.
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const BACKOFF_MIN_MS = 1000;
+export const BACKOFF_MAX_MS = 30e3;
+
+/** SQLITE_BUSY and its extended codes (BUSY_RECOVERY, BUSY_SNAPSHOT, BUSY_TIMEOUT). */
+export const isBusy = (e) => !!e && Number.isInteger(e.errcode) && (e.errcode & 0xff) === 5;
+
+/** What node:sqlite throws when busy_timeout runs out, for tests that inject it. */
+export const busyError = () => Object.assign(new Error('database is locked'), { code: 'ERR_SQLITE_ERROR', errcode: 5, errstr: 'database is locked' });
+
+const messageOf = (e) => (e && e.message ? e.message : String(e));
+
+export const RETRY_MS = [250, 500, 1000, 2000, 4000];
+
+/** Runs `fn` again after each delay while it throws SQLITE_BUSY; any other error, or the last BUSY, is thrown. */
+export async function retryBusy(fn, { delaysMs = RETRY_MS, label = 'write', log = console.error } = {}) {
+  for (let i = 0; ; i++) {
+    try { return fn(); } catch (e) {
+      if (!isBusy(e) || i >= delaysMs.length) throw e;
+      log(`${label}: database busy, retrying in ${delaysMs[i]} ms`);
+      await sleep(delaysMs[i]);
+    }
+  }
+}
+
+/**
+ * Wraps a sync or async tick. After a failure the next calls are skipped for minMs, doubling per failure in a row up to
+ * maxMs; a success resets it. A tick still running is never started twice.
+ */
+export function guardTick(name, fn, { minMs = BACKOFF_MIN_MS, maxMs = BACKOFF_MAX_MS, now = Date.now, log = console.error } = {}) {
+  let failures = 0;
+  let until = 0;
+  let pending = null;
+  const fail = (e) => {
+    failures += 1;
+    const wait = Math.min(maxMs, minMs * 2 ** (failures - 1));
+    until = now() + wait;
+    log(`${name} tick failed (${failures} in a row, next try in ${Math.round(wait / 100) / 10} s): ${messageOf(e)}`);
+  };
+  const ok = (out) => {
+    if (failures) log(`${name} tick recovered after ${failures} failure${failures === 1 ? '' : 's'}`);
+    failures = 0;
+    until = 0;
+    return out;
+  };
+  return function guarded(...args) {
+    if (pending) return pending;
+    if (now() < until) return undefined;
+    let out;
+    try { out = fn(...args); } catch (e) { fail(e); return undefined; }
+    if (!out || typeof out.then !== 'function') return ok(out);
+    pending = out.then(ok, fail).finally(() => { pending = null; });
+    return pending;
+  };
+}

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