@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/runner/busIdentity.js

@@ -0,0 +1,499 @@
+import { ADDRESS, ONLINE_MS } from '../hub/core/ids.mjs';
+
+/**
+ * Pulse 1.1.1 bus identity (F1, F1+, F4, F6). One identity per session: the Cursor hook's conversation_id is the
+ * address, and `bus register|listen --as X` run inside a session binds the alias X to it. Bindings, hook activity,
+ * register/listen proofs and other machines' presence live in runner.db tables of their own: no capture trigger, never
+ * sent to the cloud. Mail rows keep the address their sender used; delivery routes them (routedMessaging).
+ */
+
+/** After this long with no hook activity a session that ended its turn is stale: its aliases can be taken, mail to it is undeliverable. */
+export const STALE_MS = 30 * 60e3;
+/** `bus who` lists sessions active this recently, by default. */
+export const ACTIVE_MS = 15 * 60e3;
+/** A session mid-turn (or in a tool call) stays live this long without a hook event: one long Shell command. */
+export const MID_TURN_CAP_MS = 4 * 3600e3;
+/** A register or listen the runner handled this recently is the proof a binding needs; each proof binds once. */
+export const PROOF_MS = 120e3;
+/** Pulse 1.1.2 (E1): mail to an address idle this long is still stored, but its receipt says `offline since <t>`. */
+export const OFFLINE_MS = 2 * 3600e3;
+/** A session id or a Task id: the shape a `bus register --as` of a real session takes, unlike a nickname. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `did you mean` lists at most this many addresses, from sessions seen this recently. */
+const SUGGESTIONS = 3;
+const SUGGEST_FROM_MS = 7 * 24 * 3600e3;
+
+const HOOK_EVENTS = ['postToolUse', 'postToolUseFailure', 'preToolUse', 'stop', 'afterAgentResponse', 'sessionStart', 'sessionEnd', 'beforeSubmitPrompt', 'subagentStart', 'subagentStop'];
+const MID_TURN_EVENTS = new Set(['postToolUse', 'postToolUseFailure']);
+const RESERVED = new Set(['user', 'manager']);
+const COMMAND_MAX = 4000;
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS pulse_sessions (
+     session TEXT PRIMARY KEY, last_hook INTEGER NOT NULL, last_event TEXT, tool TEXT, tool_since INTEGER, ended_at INTEGER)`,
+  `CREATE TABLE IF NOT EXISTS pulse_bindings (
+     alias TEXT PRIMARY KEY, session TEXT NOT NULL, bound_at INTEGER NOT NULL, previous TEXT)`,
+  'CREATE INDEX IF NOT EXISTS pulse_bindings_session ON pulse_bindings (session)',
+  'CREATE TABLE IF NOT EXISTS pulse_proofs (address TEXT PRIMARY KEY, at INTEGER NOT NULL, via TEXT NOT NULL, used INTEGER NOT NULL DEFAULT 0)',
+  'CREATE TABLE IF NOT EXISTS pulse_remote_presence (actor_id TEXT PRIMARY KEY, machine_id TEXT, last_seen INTEGER NOT NULL, last_event TEXT)',
+];
+
+/** The bus identity tables, on the runner's hub connection (runnerSchema) or a bare hub (tests). */
+export function installBusIdentity(db) {
+  for (const sql of SCHEMA) db.prepare(sql).run();
+}
+
+/**
+ * Other machines' presence beats from a sync page (`{ actorId, machineId, lastSeen, lastEvent }`), kept apart from the
+ * hub's own presence table so this machine never sends them up as its own. Its own machine's beats are skipped.
+ */
+export function applyRemotePresence(db, beats, ownMachine) {
+  let statement = null;
+  let n = 0;
+  for (const b of beats || []) {
+    if (!b || !ADDRESS.test(String(b.actorId || '')) || !b.machineId || b.machineId === ownMachine) continue;
+    const seen = Number(b.lastSeen);
+    if (!Number.isFinite(seen)) continue;
+    statement ??= db.prepare(`INSERT INTO pulse_remote_presence (actor_id, machine_id, last_seen, last_event) VALUES (?, ?, ?, ?)
+      ON CONFLICT (actor_id) DO UPDATE SET machine_id = excluded.machine_id, last_seen = excluded.last_seen, last_event = excluded.last_event
+      WHERE excluded.last_seen > pulse_remote_presence.last_seen`);
+    n += Number(statement.run(b.actorId, b.machineId, seen, typeof b.lastEvent === 'string' ? b.lastEvent.slice(0, 40) : null).changes);
+  }
+  return n;
+}
+
+const minutes = (ms) => Math.max(0, Math.floor(ms / 60e3));
+const clockOf = (at) => new Date(at).toISOString().slice(11, 16);
+
+/** Levenshtein distance, stopping early once it passes `cap`. */
+function editDistance(a, b, cap = 40) {
+  if (Math.abs(a.length - b.length) > cap) return cap + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      next[j] = Math.min(prev[j] + 1, next[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      best = Math.min(best, next[j]);
+    }
+    if (best > cap) return cap + 1;
+    prev = next;
+  }
+  return prev[b.length];
+}
+
+const commonPrefix = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[i] === b[i]) i++; return i; };
+
+/**
+ * The closest of `candidates` (`{ key, address, label }`) to `wanted`: by the longest common prefix, then the smallest
+ * edit distance, each address once. A candidate is close when it shares 4 characters of prefix or is within about a
+ * third of its length in edits.
+ */
+export function closestAddresses(wanted, candidates, limit = SUGGESTIONS) {
+  const w = String(wanted || '').toLowerCase();
+  const ranked = [];
+  for (const c of candidates) {
+    const key = String(c.key || '').toLowerCase();
+    if (!key || key === w) continue;
+    const prefix = commonPrefix(w, key);
+    const cap = Math.max(2, Math.floor(Math.max(w.length, key.length) / 3));
+    const distance = editDistance(w, key, cap);
+    if (prefix < 4 && distance > cap) continue;
+    ranked.push({ ...c, prefix, distance });
+  }
+  ranked.sort((a, b) => b.prefix - a.prefix || a.distance - b.distance || a.address.localeCompare(b.address));
+  const out = [];
+  for (const r of ranked) {
+    if (out.some((o) => o.address === r.address)) continue;
+    out.push({ address: r.address, ...(r.label && r.label !== r.address ? { label: r.label } : {}) });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Simple commands of a shell line, each as words with quotes removed: split on unquoted `&&`, `||`, `;`, `|` and new
+ * lines. Heredoc bodies are dropped first, so a register line inside one is never a command.
+ */
+export function shellCommands(text) {
+  const lines = String(text || '').slice(0, COMMAND_MAX).split('\n');
+  const kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    kept.push(lines[i]);
+    const heredoc = lines[i].match(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/);
+    if (!heredoc) continue;
+    while (i + 1 < lines.length && lines[i + 1].trim() !== heredoc[2]) i++;
+    i++;
+  }
+  const commands = [];
+  let words = [];
+  let word = null;
+  let quote = null;
+  const line = kept.join('\n');
+  const endWord = () => { if (word !== null) words.push(word); word = null; };
+  const endCommand = () => { endWord(); if (words.length) commands.push(words); words = []; };
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (c === '\\' && quote === '"' && i + 1 < line.length) word += line[++i];
+      else word += c;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; word = word ?? ''; continue; }
+    if (c === '\\' && i + 1 < line.length) { word = (word ?? '') + line[++i]; continue; }
+    if (c === '\n' || c === ';' || c === '|' || (c === '&' && line[i + 1] === '&')) { if (c === '&' || (c === '|' && line[i + 1] === '|')) i++; endCommand(); continue; }
+    if (c === ' ' || c === '\t') { endWord(); continue; }
+    word = (word ?? '') + c;
+  }
+  endCommand();
+  return commands;
+}
+
+const basename = (word) => String(word).split('/').pop();
+
+/**
+ * The aliases a Shell command registers or listens as: only a real hub CLI call, `node <…/hub.mjs> bus register|listen
+ * … --as <X>`. An echo, a grep, a publish body or a heredoc never counts.
+ */
+export function busAliases(command) {
+  const out = [];
+  for (let words of shellCommands(command)) {
+    while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words = words.slice(1);
+    if (!words.length || basename(words[0]) !== 'node') continue;
+    let i = 1;
+    while (i < words.length && words[i].startsWith('-')) i++;
+    if (basename(words[i] || '') !== 'hub.mjs' || words[i + 1] !== 'bus' || !['register', 'listen'].includes(words[i + 2])) continue;
+    const at = words.indexOf('--as', i + 3);
+    const alias = at > 0 ? words[at + 1] : null;
+    if (alias && ADDRESS.test(alias)) out.push({ action: words[i + 2], alias });
+  }
+  return out;
+}
+
+/** A session's turn from its last hook event: in a tool call, mid-turn, turn ended, or ended (sessionEnd). */
+function turnOf(row, now) {
+  if (!row) return null;
+  if (row.ended_at && row.ended_at >= row.last_hook) return 'ended';
+  if (row.last_event === 'preToolUse' && now - (row.tool_since || row.last_hook) < MID_TURN_CAP_MS) return 'in-tool';
+  if (MID_TURN_EVENTS.has(row.last_event) && now - row.last_hook < MID_TURN_CAP_MS) return 'mid-turn';
+  return 'turn-ended';
+}
+
+/** Live: a reader now. In a tool call or mid-turn up to the cap; a turn that ended, for STALE_MS. */
+const liveTurn = (turn, idle) => turn === 'in-tool' || turn === 'mid-turn' || (turn === 'turn-ended' && idle < STALE_MS);
+
+export function createBusIdentity(hub, { now: clock = Date.now } = {}) {
+  const { db, registry } = hub;
+  installBusIdentity(db);
+  const q = {
+    session: db.prepare('SELECT * FROM pulse_sessions WHERE session = ?'),
+    sessions: db.prepare('SELECT * FROM pulse_sessions'),
+    touch: db.prepare(`INSERT INTO pulse_sessions (session, last_hook, last_event, tool, tool_since, ended_at) VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT (session) DO UPDATE SET last_hook = MAX(pulse_sessions.last_hook, excluded.last_hook), last_event = excluded.last_event,
+        tool = excluded.tool, tool_since = excluded.tool_since, ended_at = COALESCE(excluded.ended_at, pulse_sessions.ended_at)`),
+    seedSession: db.prepare('INSERT OR IGNORE INTO pulse_sessions (session, last_hook, last_event) VALUES (?, ?, ?)'),
+    binding: db.prepare('SELECT * FROM pulse_bindings WHERE alias = ?'),
+    bindings: db.prepare('SELECT * FROM pulse_bindings'),
+    aliases: db.prepare('SELECT alias FROM pulse_bindings WHERE session = ? ORDER BY bound_at'),
+    bind: db.prepare(`INSERT INTO pulse_bindings (alias, session, bound_at, previous) VALUES (?, ?, ?, ?)
+      ON CONFLICT (alias) DO UPDATE SET session = excluded.session, bound_at = excluded.bound_at, previous = excluded.previous`),
+    proof: db.prepare('SELECT * FROM pulse_proofs WHERE address = ?'),
+    prove: db.prepare(`INSERT INTO pulse_proofs (address, at, via, used) VALUES (?, ?, ?, 0)
+      ON CONFLICT (address) DO UPDATE SET at = excluded.at, via = excluded.via, used = 0`),
+    refreshProof: db.prepare("INSERT INTO pulse_proofs (address, at, via, used) VALUES (?, ?, 'listen', 0) ON CONFLICT (address) DO UPDATE SET at = MAX(pulse_proofs.at, excluded.at)"),
+    useProof: db.prepare('UPDATE pulse_proofs SET used = 1 WHERE address = ?'),
+    remote: db.prepare('SELECT * FROM pulse_remote_presence WHERE actor_id = ?'),
+  };
+
+  /**
+   * Every chat the hub already knows to be a session, before its next hook: hook-seen and transcript-found actors, and
+   * presence rows whose last event came from a hook. Without this, right after an upgrade another session could take a
+   * live session's own id as its alias. A bound alias is never one: its heartbeats copy its session's hook events.
+   */
+  function seed() {
+    const marks = HOOK_EVENTS.map(() => '?').join(',');
+    const rows = db.prepare(`SELECT a.id AS id, COALESCE(p.last_seen, a.last_at, 0) AS seen, CASE WHEN p.last_event IN (${marks}) THEN p.last_event END AS event
+      FROM actors a LEFT JOIN presence p ON p.actor_id = a.id
+      WHERE (a.source IN ('hook', 'transcript') OR a.cursor_title IS NOT NULL OR a.prompt_title IS NOT NULL OR p.last_event IN (${marks}))
+        AND a.id NOT IN (SELECT alias FROM pulse_bindings)`).all(...HOOK_EVENTS, ...HOOK_EVENTS);
+    for (const r of rows) if (ADDRESS.test(r.id) && !RESERVED.has(r.id)) q.seedSession.run(r.id, Number(r.seen) || 0, r.event);
+  }
+  seed();
+
+  const sessionRow = (id) => q.session.get(id) || null;
+  const sessionOf = (address) => {
+    const bound = q.binding.get(address);
+    if (bound) return bound.session;
+    return sessionRow(address) ? address : null;
+  };
+  const aliasesOf = (session) => q.aliases.all(session).map((r) => r.alias).filter((a) => a !== session);
+
+  /**
+   * The addresses a session's hook serves as one inbox: the session and every alias bound to it. Anything else (an
+   * alias, an unknown address) is only itself.
+   */
+  function addressesOf(address) {
+    if (q.binding.get(address) || !sessionRow(address)) return [address];
+    return [address, ...aliasesOf(address)];
+  }
+
+  /**
+   * Whose mail a `bus listen` or `bus ack` as `principal` may take, given the session that ran it (`caller`, the CLI's
+   * CURSOR_CONVERSATION_ID, or null outside Cursor). The holding session itself gets its whole inbox, whether it names
+   * itself or one of its aliases. Another session is refused (`held`) on an alias a live session holds, before any
+   * claim. Everyone else, a caller outside Cursor included, gets the mail sent to `principal` literally.
+   */
+  function inboxFor(principal, caller = null, now = clock()) {
+    const bound = q.binding.get(principal);
+    const holder = bound ? bound.session : sessionRow(principal) ? principal : null;
+    if (holder && caller === holder) return { addresses: [...new Set([principal, holder, ...aliasesOf(holder)])] };
+    if (caller && bound && bound.session !== principal) {
+      const act = activity(bound.session, now);
+      if (act && act.live) return { held: { session: bound.session, idleMin: minutes(act.idle) } };
+    }
+    return { addresses: [principal] };
+  }
+
+  /** A session's turn and idle time, from this machine's hooks or another machine's presence. */
+  function activity(session, now = clock()) {
+    const row = sessionRow(session);
+    if (row) {
+      const turn = turnOf(row, now);
+      const idle = now - row.last_hook;
+      return { turn, idle, live: liveTurn(turn, idle), tool: turn === 'in-tool' ? row.tool : null, toolSince: turn === 'in-tool' ? row.tool_since : null, remote: false };
+    }
+    const beat = q.remote.get(session);
+    if (beat && HOOK_EVENTS.includes(beat.last_event)) {
+      const turn = turnOf({ last_hook: beat.last_seen, last_event: beat.last_event, tool_since: beat.last_seen }, now);
+      const idle = now - beat.last_seen;
+      return { turn, idle, live: liveTurn(turn, idle), tool: null, toolSince: null, remote: true };
+    }
+    return null;
+  }
+
+  const listening = (address, now) => {
+    const local = registry.presence(address);
+    if (local && local.last_event === 'listen' && now - local.last_seen < ONLINE_MS) return true;
+    const beat = q.remote.get(address);
+    return !!(beat && beat.last_event === 'listen' && now - beat.last_seen < ONLINE_MS);
+  };
+
+  /** When `address` last listened, from this machine's presence or another machine's; null if it never did. */
+  const lastListen = (address) => {
+    const local = registry.presence(address);
+    const beat = q.remote.get(address);
+    return Math.max(local && local.last_event === 'listen' ? local.last_seen : 0, beat && beat.last_event === 'listen' ? beat.last_seen : 0) || null;
+  };
+
+  /**
+   * Pulse 1.1.2 (E1): whether `address` is one the bus knows, so mail to `agent/<address>` can ever be read. Known: the
+   * hub's own addresses, a bound alias, a session a hook has shown (here, or by another machine's presence), an address
+   * that has listened, and a session or Task id that registered itself. A nickname nobody bound is not. A reply's
+   * destination is the original sender, never typed, so there any session or Task id passes and only a nickname is checked.
+   */
+  function known(address, { reply = false } = {}) {
+    if (RESERVED.has(address) || q.binding.get(address) || sessionRow(address)) return true;
+    if (reply && SESSION_ID.test(address)) return true;
+    const beat = q.remote.get(address);
+    if (beat && (HOOK_EVENTS.includes(beat.last_event) || beat.last_event === 'listen')) return true;
+    if (lastListen(address)) return true;
+    const actor = registry.get(address);
+    return !!actor && (actor.source === 'hook' || actor.source === 'transcript' || (actor.source === 'registered' && SESSION_ID.test(address)));
+  }
+
+  /** E1's `did you mean`: the closest session ids, bound aliases and the names those sessions registered. */
+  function suggest(address, now = clock()) {
+    const candidates = [];
+    const named = (id) => { const a = registry.get(id); return a ? a.persona_name || a.cursor_title || null : null; };
+    for (const s of q.sessions.all()) {
+      if (now - s.last_hook > SUGGEST_FROM_MS) continue;
+      const label = named(s.session);
+      candidates.push({ key: s.session, address: s.session, label });
+      if (label) candidates.push({ key: label.replace(/\s+/g, '-'), address: s.session, label });
+    }
+    for (const b of q.bindings.all()) candidates.push({ key: b.alias, address: b.alias, label: `bound to ${b.session}` });
+    for (const a of registry.all()) {
+      if (a.source === 'registered' && SESSION_ID.test(a.id)) candidates.push({ key: a.id, address: a.id, label: a.persona_name });
+    }
+    return closestAddresses(address, candidates);
+  }
+
+  /**
+   * Whether anyone can read mail to `address` now (F1, F2+): `queued` with how it is reached, or `undeliverable` with
+   * why. A reader is the hub (user, manager), a `bus listen` in the last 90 s, or the session holding the address while
+   * live. A register heartbeat alone never is one. Idle more than OFFLINE_MS: `offline`, with when it was last seen.
+   */
+  function reach(address, now = clock()) {
+    if (RESERVED.has(address)) return { state: 'queued', reach: 'hub' };
+    if (listening(address, now)) return { state: 'queued', reach: 'listener' };
+    const bound = q.binding.get(address);
+    const session = bound ? bound.session : address;
+    const act = activity(session, now);
+    if (!act) {
+      const listened = lastListen(address);
+      return listened && now - listened > OFFLINE_MS ? { state: 'undeliverable', reason: 'offline', offlineSince: listened } : { state: 'undeliverable', reason: 'no-reader' };
+    }
+    const facts = { session, idleMin: minutes(act.idle) };
+    if (!act.live && act.idle > OFFLINE_MS) return { state: 'undeliverable', reason: 'offline', offlineSince: now - act.idle, ...facts };
+    if (!act.live) return { state: 'undeliverable', reason: 'stale', ...facts };
+    return {
+      state: 'queued', reach: act.remote ? 'remote' : 'session', ...facts,
+      ...(act.turn === 'turn-ended' ? { turnEnded: true } : {}), ...(act.turn === 'mid-turn' || act.turn === 'in-tool' ? { midTurn: true } : {}),
+    };
+  }
+
+  /** A hook event from `session`: its activity, before handleHook. Returns the time of its previous hook, or null. */
+  function sawHook(input, now = clock()) {
+    const session = input.conversation_id;
+    const prior = sessionRow(session);
+    const event = String(input.hook_event_name);
+    const tool = typeof input.tool_name === 'string' ? input.tool_name.slice(0, 60) : null;
+    q.touch.run(session, now, event, event === 'preToolUse' ? tool : null, event === 'preToolUse' ? now : null, event === 'sessionEnd' ? now : null);
+    for (const alias of aliasesOf(session)) registry.heartbeat(alias, { event, tool, at: now });
+    return prior ? prior.last_hook : null;
+  }
+
+  /** The runner handled `bus register --as X` (or a listen's own register): one proof, for one binding. */
+  const proved = (address, via = 'register', now = clock()) => { if (ADDRESS.test(String(address || ''))) q.prove.run(address, now, via); };
+  /** A `bus listen --as X` poll: keeps a long listen's proof fresh without re-arming a used one. */
+  const listened = (address, now = clock()) => { if (ADDRESS.test(String(address || ''))) q.refreshProof.run(address, now); };
+
+  /**
+   * The aliases a Shell command in this hook registered or listened as, bound to the hook's session or refused. Each
+   * result is reported back to the session (notices), since the CLI ran before the hook could know.
+   */
+  function bindFromHook(input, now = clock()) {
+    const event = input.hook_event_name;
+    if (event !== 'postToolUse' && event !== 'postToolUseFailure') return [];
+    const command = input.tool_input && typeof input.tool_input.command === 'string' ? input.tool_input.command : null;
+    if (!command) return [];
+    const session = input.conversation_id;
+    const results = [];
+    for (const { alias } of busAliases(command)) {
+      if (results.some((r) => r.alias === alias)) continue;
+      results.push({ alias, ...bindOne(session, alias, now) });
+    }
+    return results;
+  }
+
+  function bindOne(session, alias, now) {
+    if (alias === session) return { result: 'self' };
+    if (RESERVED.has(alias)) return { result: 'refused', reason: 'reserved' };
+    const held = q.binding.get(alias);
+    if (held && held.session === session) return { result: 'already' };
+    if (sessionRow(alias)) return { result: 'refused', reason: 'session-id' };
+    if (held) {
+      const act = activity(held.session, now);
+      if (act && act.live) return { result: 'refused', reason: 'held', holder: held.session, idleMin: minutes(act.idle) };
+    } else {
+      const elsewhere = activity(alias, now);
+      if (elsewhere && elsewhere.live) return { result: 'refused', reason: 'held', holder: 'a session on another machine', idleMin: minutes(elsewhere.idle) };
+    }
+    const proof = q.proof.get(alias);
+    if (!proof || proof.used || now - proof.at > PROOF_MS) return { result: 'refused', reason: 'unproven' };
+    q.bind.run(alias, session, now, held ? held.session : null);
+    q.useProof.run(alias);
+    if (held) {
+      registry.appendEvent({ at: now, kind: 'BUS REBIND', actor: session, payload: { from: session, to: alias, type: 'BUS REBIND', text: `${alias} moved from ${held.session} to ${session}` } });
+      return { result: 'rebound', previous: held.session, idleMin: minutes(now - (sessionRow(held.session)?.last_hook ?? held.bound_at)) };
+    }
+    return { result: 'bound' };
+  }
+
+  /** What the session is told about each binding in its hook answer. */
+  function notices(results, session) {
+    const lines = [];
+    for (const r of results) {
+      if (r.result === 'bound') lines.push(`Bus alias \`${r.alias}\` is now bound to this session (${session}): mail to it reaches you here. Reply with \`--as ${r.alias}\` or \`--as ${session}\`.`);
+      else if (r.result === 'rebound') lines.push(`Bus alias \`${r.alias}\` is now bound to this session (${session}). It was held by ${r.previous}, idle ${r.idleMin} min; mail still queued for it comes to you.`);
+      else if (r.reason === 'held') lines.push(`Not bound: bus alias \`${r.alias}\` is held by live session ${r.holder} (active ${r.idleMin} min ago). Use your own address ${session}, or pick another alias.`);
+      else if (r.reason === 'session-id') lines.push(`Not bound: \`${r.alias}\` is another session's own bus address. Use your own address ${session}.`);
+      else if (r.reason === 'reserved') lines.push(`Not bound: \`${r.alias}\` is the hub's own address. Use your own address ${session}.`);
+      else if (r.reason === 'unproven') lines.push(`Not bound: the hub did not see \`bus register --as ${r.alias}\` succeed just now. Run it again as a command of its own.`);
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * `bus who` (F4, F6): active sessions by default, grouped by repo and task, each with its aliases folded in and an
+   * activity line; `all` adds every registration and session seen in the last day. The registration fields are the
+   * ones `registrations()` gives, so old readers keep working.
+   */
+  function who({ all = false, minutes: windowMin = ACTIVE_MS / 60e3, now = clock() } = {}) {
+    const windowMs = Math.max(1, Number(windowMin) || ACTIVE_MS / 60e3) * 60e3;
+    const dir = new Map(registry.directory(now).map((a) => [a.id, a]));
+    const presence = registry.presences();
+    const bindings = q.bindings.all();
+    const boundTo = new Map(bindings.map((b) => [b.alias, b.session]));
+    const sessions = new Map(q.sessions.all().map((s) => [s.session, s]));
+    const ids = new Set([...registry.registrations(now).map((r) => r.id), ...[...sessions.values()].filter((s) => now - s.last_hook < 24 * 3600e3).map((s) => s.session)]);
+    for (const b of bindings) ids.add(b.session);
+    const entries = [];
+    for (const id of ids) {
+      if (boundTo.has(id) && boundTo.get(id) !== id) continue;
+      const actor = dir.get(id) || null;
+      const aliases = aliasesOf(id);
+      const named = [actor, ...aliases.map((a) => dir.get(a))].find((a) => a && a.source === 'registered') || actor;
+      const act = activity(id, now);
+      const seenAt = Math.max(act ? now - act.idle : 0, presence.get(id)?.last_seen || 0, actor ? actor.seenAt || 0 : 0);
+      const listen = listening(id, now) || aliases.some((a) => listening(a, now));
+      const idle = now - seenAt;
+      const [repo, task] = String((actor && actor.stream_key) || '').split('/');
+      const entry = {
+        id, role: named ? named.role : null, name: named ? named.persona_name : null, topics: named ? named.topics || [] : [],
+        parent: actor ? actor.parent_id : null, seenAt, online: !!(actor && actor.online) || listen,
+        label: (named && named.persona_name) || (actor && actor.title) || id, aliases,
+        repo: (actor && actor.repo) || repo || null, task: task || null, idleMin: minutes(idle), turn: act ? act.turn : null,
+      };
+      if (act && act.turn === 'in-tool') entry.activity = `in a tool call since ${clockOf(act.toolSince)} (${act.tool || 'tool'})`;
+      else if (act && act.turn === 'mid-turn' && act.idle >= STALE_MS) entry.activity = `mid-turn, no activity ${minutes(act.idle)} min`;
+      if (idle >= STALE_MS && !(act && act.live) && !listen && !RESERVED.has(id)) entry.stale = `no activity ${minutes(idle)} min`;
+      entry.active = RESERVED.has(id) || listen || idle < windowMs || !!(act && (act.turn === 'mid-turn' || act.turn === 'in-tool'));
+      entries.push(entry);
+    }
+    const activeIds = new Set(entries.filter((e) => e.active).map((e) => e.id));
+    for (const e of entries) if (!e.active && entries.some((c) => c.parent === e.id && activeIds.has(c.id))) e.active = true;
+    const shown = entries.filter((e) => all || e.active);
+    const groups = new Map();
+    for (const e of shown) {
+      const key = `${e.repo || ''}\0${e.task || ''}`;
+      if (!groups.has(key)) groups.set(key, { repo: e.repo, task: e.task, sessions: [] });
+      groups.get(key).sessions.push(e.id);
+    }
+    return { registrations: shown.map(({ active: _active, ...e }) => e), groups: [...groups.values()], window: { minutes: windowMs / 60e3, all: !!all } };
+  }
+
+  return { addressesOf, inboxFor, sessionOf, aliasesOf, activity, known, suggest, reach, sawHook, proved, listened, bindFromHook, notices, who };
+}
+
+/**
+ * The hub's messaging as seen by whoever acts as `addresses[0]`: mail to any of `addresses` (a session and its
+ * aliases) is peeked, claimed, shown and answered as one inbox. A message with a row for more than one of them is
+ * shown once, and every one of its rows is settled together. Calls for any other address pass straight through.
+ */
+export function routedMessaging(messaging, addresses) {
+  if (!addresses || addresses.length <= 1) return messaging;
+  const [self] = addresses;
+  const once = (rows) => { const seen = new Set(); return rows.filter((m) => !seen.has(m.id) && seen.add(m.id)); };
+  const oldestFirst = (a, b) => (a.at || 0) - (b.at || 0);
+  const each = (fn) => addresses.flatMap((a) => fn(a));
+  return {
+    ...messaging,
+    peek: (as, opts = {}) => (as === self ? once(each((a) => messaging.peek(a, opts))).sort(oldestFirst).slice(0, opts.limit ?? 20) : messaging.peek(as, opts)),
+    claim: (as, opts = {}) => (as === self ? once(each((a) => messaging.claim(a, opts))).sort(oldestFirst) : messaging.claim(as, opts)),
+    markDelivered: (as, ids, opts) => (as === self ? addresses.reduce((n, a) => n + messaging.markDelivered(a, ids, opts), 0) : messaging.markDelivered(as, ids, opts)),
+    sideUnanswered: (as) => (as === self ? once(each((a) => messaging.sideUnanswered(a))).sort(oldestFirst) : messaging.sideUnanswered(as)),
+    awaiting: (as) => (as === self ? once(each((a) => messaging.awaiting(a))) : messaging.awaiting(as)),
+    releaseAwaiting: (as) => (as === self ? addresses.reduce((n, a) => n + messaging.releaseAwaiting(a), 0) : messaging.releaseAwaiting(as)),
+    ack: (as, id, opts = {}, directory) => {
+      if (as !== self) return messaging.ack(as, id, opts, directory);
+      let first = null;
+      for (const a of addresses) {
+        const r = messaging.ack(a, id, first ? {} : opts, directory);
+        if (!r.error && !first) first = r;
+      }
+      return first || messaging.ack(self, id, opts, directory);
+    },
+  };
+}

package/src/runner/capture.js

@@ -0,0 +1,103 @@
+import { withTx } from '../hub/core/db.mjs';
+
+/**
+ * Which hub rows reach the cloud and the key columns that name one. Leases, imports, settings and the hub's file
+ * quarantine stay on the machine.
+ */
+const CAPTURED = [
+  { table: 'messages', keys: ['id'], ops: ['INSERT', 'DELETE'] },
+  { table: 'deliveries', keys: ['message_id', 'recipient'], ops: ['INSERT', 'UPDATE', 'DELETE'] },
+  { table: 'actors', keys: ['id'], ops: ['INSERT', 'UPDATE'] },
+  { table: 'facts', keys: ['kind', 'key'], ops: ['INSERT', 'UPDATE', 'DELETE'] },
+  { table: 'events', keys: ['id'], ops: ['INSERT'] },
+];
+
+const SCHEMA = [
+  'CREATE TABLE IF NOT EXISTS pulse_ctx (one INTEGER PRIMARY KEY CHECK (one = 1), applying INTEGER NOT NULL DEFAULT 0)',
+  'INSERT OR IGNORE INTO pulse_ctx (one, applying) VALUES (1, 0)',
+  'CREATE TABLE IF NOT EXISTS pulse_capture (id INTEGER PRIMARY KEY AUTOINCREMENT, tbl TEXT NOT NULL, op TEXT NOT NULL, k1 TEXT NOT NULL, k2 TEXT)',
+];
+
+function triggerSql({ table, keys, ops }) {
+  return ops.map((op) => {
+    const row = op === 'DELETE' ? 'OLD' : 'NEW';
+    const [k1, k2] = keys.map((k) => `${row}.${k}`);
+    return `CREATE TRIGGER IF NOT EXISTS pulse_capture_${table}_${op.toLowerCase()} AFTER ${op} ON ${table}
+      WHEN (SELECT applying FROM pulse_ctx) = 0
+      BEGIN INSERT INTO pulse_capture (tbl, op, k1, k2) VALUES ('${table}', '${op.toLowerCase()}', ${k1}, ${k2 || 'NULL'}); END`;
+  });
+}
+
+/** The capture tables and triggers, created once on the runner's hub connection. */
+export function installCapture(db) {
+  for (const sql of [...SCHEMA, ...CAPTURED.flatMap(triggerSql)]) db.prepare(sql).run();
+}
+
+/**
+ * Turns every captured hub write into outbox commands inside the transaction that made it.
+ *
+ * `tx(fn, { guard })` runs fn in one write transaction (the ported core's own withTx calls join it), drains the trigger
+ * journal through `mapping.commands(change, db)` into the outbox, then runs `guard`; a guard that throws rolls the
+ * hub write and its commands back together. `applying(fn)` writes with the triggers off, for rows that came from the
+ * cloud: other connections never see the flag set, because SQLite serializes writers and the flag is set and reset
+ * inside one write transaction. `pump()` drains what writes outside any `tx` left in the journal.
+ */
+export function createCapture({ db, store, mapping, log = () => {} }) {
+  const journal = db.prepare('SELECT id, tbl, op, k1, k2 FROM pulse_capture ORDER BY id');
+  const clear = db.prepare('DELETE FROM pulse_capture WHERE id <= ?');
+  const setApplying = db.prepare('UPDATE pulse_ctx SET applying = ? WHERE one = 1');
+
+  function drain() {
+    const rows = journal.all();
+    if (!rows.length) return 0;
+    const latest = new Map();
+    for (const row of rows) {
+      const id = `${row.tbl}\0${row.k1}\0${row.k2 ?? ''}`;
+      latest.delete(id);
+      latest.set(id, row);
+    }
+    const entries = [];
+    for (const { tbl, op, k1, k2 } of latest.values()) {
+      const change = { tbl, op, k1, k2 };
+      try {
+        entries.push(...mapping.commands(change, db));
+      } catch (error) {
+        // A full outbox refuses the write itself (507 pulse_backlog), so the caller is told.
+        if (error.code === 'pulse_backlog') throw error;
+        // One row the mapping can't turn into a command must not refuse the local write that made it.
+        store.refuse(
+          { key: `capture:${tbl}:${k1}:${k2 ?? '-'}:${rows.at(-1).id}`, group: `capture:${tbl}`, type: 'capture', payload: change, source: 'capture' },
+          { code: 'capture_failed', message: String(error?.message || error).slice(0, 300) },
+        );
+        log('capture_failed', { tbl, op, code: error?.code || 'capture_failed' });
+      }
+    }
+    if (entries.length) store.enqueue(entries);
+    clear.run(rows.at(-1).id);
+    return entries.length;
+  }
+
+  function tx(fn, { guard = null, label = 'capture' } = {}) {
+    return withTx(db, () => {
+      const out = fn();
+      drain();
+      if (guard) guard();
+      return out;
+    }, label);
+  }
+
+  function applying(fn) {
+    return withTx(db, () => {
+      setApplying.run(1);
+      try {
+        return fn();
+      } finally {
+        setApplying.run(0);
+      }
+    }, 'apply');
+  }
+
+  const pump = () => withTx(db, drain, 'capture pump');
+
+  return { tx, applying, pump, drain };
+}

package/src/runner/captureMapping.js

@@ -0,0 +1,21 @@
+import os from 'node:os';
+import { HubError } from '../lib/errors.js';
+import { createHubCapture } from './hubCapture.js';
+
+/** Captures nothing: a runner that only serves the local hub (tests, rehearsals with no cloud). */
+const NONE = Object.freeze({ commands: () => [], sweep: () => null });
+
+/**
+ * The capture mapping for a runner: `hub` turns every captured row into the commands the Phase 2 shadow would send
+ * (src/runner/hubCapture.js); `none` captures nothing. Returns a factory of the runner's store.
+ */
+export function mappingFor(name, { hubDir, roots = [], approvedRoots = [], secrets = () => [], home = os.homedir() } = {}) {
+  switch (name) {
+    case 'none':
+      return () => NONE;
+    case 'hub':
+      return (store) => createHubCapture({ store, hubDir, roots, home, approvedRoots, secrets });
+    default:
+      throw new HubError('bad_config', `Unknown capture mapping "${name}"`);
+  }
+}