@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/runner/hubCapture.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { HubSnapshot, rowActor } from '../lib/hubDbReader.js';
+import { actorPayload, keyPart, receiptEvents, without } from '../lib/hubMapping.js';
+import { ACTOR_TIME_FIELDS, ALL_FACT_KINDS, FACT_KINDS, HubScan, REMOVABLE_KINDS } from '../lib/hubScan.js';
+import { canonicalJson } from '../lib/planContract.js';
+import { UploadRedactor } from '../lib/uploadRedactor.js';
+
+const DELIVERIES_REFRESH_MS = 30_000;
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+const short = (text) => sha(text).slice(0, 12);
+
+const parse = (text) => {
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Capture's mapping from a changed hub row to outbox commands: the Phase 2 shadow's own per-row code (HubScan), run
+ * on the runner's connection inside the write transaction, so a row captured here gets exactly the key, payload,
+ * redaction and version the shadow would give it, and a later shadow pass over runner.db finds nothing new.
+ * Presence is not captured (heartbeats are not log events, D10); the daemon sends it as before.
+ */
+export function createHubCapture({ store, hubDir, roots, home, approvedRoots = [], secrets = () => [], now = Date.now }) {
+  const scan = new HubScan({
+    store, reader: null, hubDir, roots, now, secrets,
+    redaction: new UploadRedactor({ workspace: path.dirname(hubDir), home, approvedRoots }),
+  });
+  let deliveries = [];
+  let deliveriesAt = -Infinity;
+  const contextFor = (db) => {
+    if (now() - deliveriesAt >= DELIVERIES_REFRESH_MS) {
+      deliveries = db.prepare("SELECT payload FROM facts WHERE kind = 'delivery'").all().map((row) => parse(row.payload)).filter(Boolean);
+      deliveriesAt = now();
+    }
+    return scan.context({ now: now(), shadow: true, deliveries });
+  };
+
+  function messageWithRecipients(snapshot, db, id) {
+    const message = db.prepare('SELECT rowid AS _rowid, * FROM messages WHERE id = ?').get(id);
+    if (!message) return null;
+    return { message: { ...message, meta: parse(message.meta) ?? {} }, to: snapshot.recipients([id]).get(id) || [] };
+  }
+
+  return {
+    scan,
+    commands(change, db) {
+      const snapshot = new HubSnapshot(db);
+      const context = contextFor(db);
+      switch (change.tbl) {
+        case 'messages': {
+          if (change.op === 'delete') {
+            const recent = db.prepare('SELECT id, grp FROM recent_message WHERE id = ?').get(change.k1);
+            if (recent && !snapshot.messageExists(change.k1)) scan.messageGone(context, { id: recent.id, group: recent.grp });
+            return [];
+          }
+          const found = messageWithRecipients(snapshot, db, change.k1);
+          if (found) scan.messageRow(context, found.message, found.to);
+          return [];
+        }
+        case 'deliveries': {
+          if (change.op === 'delete') return [];
+          if (!store.known(change.k1)) {
+            const found = messageWithRecipients(snapshot, db, change.k1);
+            if (found) scan.messageRow(context, found.message, found.to);
+            return [];
+          }
+          const row = snapshot.receipt(change.k1, change.k2);
+          scan.receiptRow(context, { messageId: change.k1, recipient: change.k2, state: store.receiptState(change.k1, change.k2), row });
+          return [];
+        }
+        case 'actors': {
+          const row = db.prepare('SELECT * FROM actors WHERE id = ?').get(change.k1);
+          if (row) scan.actorRow(context, rowActor(row));
+          return [];
+        }
+        case 'facts': {
+          const row = db.prepare('SELECT kind, key, payload, updated_at FROM facts WHERE kind = ? AND key = ?').get(change.k1, change.k2);
+          if (row) scan.factRow(context, { ...row });
+          else if (REMOVABLE_KINDS.includes(change.k1)) scan.factRemoved(context, change.k1, change.k2);
+          return [];
+        }
+        case 'events': {
+          const event = db.prepare('SELECT id, at, kind, actor, payload FROM events WHERE id = ?').get(change.k1);
+          if (event) scan.eventRow(context, { ...event, payload: parse(event.payload) ?? {} });
+          return [];
+        }
+        default:
+          return [];
+      }
+    },
+
+    /**
+     * A row the sync applier just wrote from the cloud: remember the version the shadow would have sent for it, so
+     * neither capture's sweep nor a later shadow pass sends it back as this machine's own change.
+     */
+    adopt(change, db) {
+      const snapshot = new HubSnapshot(db);
+      const context = contextFor(db);
+      switch (change.tbl) {
+        case 'actors': {
+          const row = db.prepare('SELECT * FROM actors WHERE id = ?').get(change.k1);
+          if (!row) return;
+          const actor = rowActor(row);
+          const entity = `actor:${actor.id}`;
+          const prepared = scan.prepare(context, 'actors', {
+            type: 'actor.updated', group: entity, entity, prefix: keyPart('actor', actor.id), separator: '@', payload: actorPayload(actor),
+          });
+          if (!prepared.version) return;
+          const staticSha = short(canonicalJson(without(prepared.entry.payload.actor, ...ACTOR_TIME_FIELDS)));
+          store.setVersion(entity, { ...prepared.version, rawSha: sha(JSON.stringify(actor)), staticSha });
+          return;
+        }
+        case 'facts': {
+          const row = db.prepare('SELECT kind, key, payload, updated_at FROM facts WHERE kind = ? AND key = ?').get(change.k1, change.k2);
+          const fact = row && parse(row.payload);
+          if (!fact || !FACT_KINDS.includes(row.kind)) return;
+          scan.factCommands(context, { ...row }, fact).forEach((item, index) => {
+            if (item.version) store.setVersion(item.version.entity, { ...item.version, rawSha: index === 0 ? sha(row.payload) : null, staticSha: null });
+          });
+          return;
+        }
+        case 'deliveries': {
+          const row = snapshot.receipt(change.k1, change.k2);
+          if (row) store.setReceiptState(change.k1, change.k2, receiptEvents(row, row.topic, row.expires_at).state);
+          return;
+        }
+        default:
+      }
+    },
+
+    /**
+     * Everything capture coalesced away, picked up again: actors whose only change was their clock (sent at most
+     * once a minute) and facts a delivery dropped. Read and queued in the caller's transaction, row by row.
+     */
+    sweep(db) {
+      const snapshot = new HubSnapshot(db);
+      const context = contextFor(db);
+      for (const actor of snapshot.actors()) scan.actorRow(context, actor);
+      const present = new Map(REMOVABLE_KINDS.map((kind) => [kind, new Set()]));
+      for (const row of snapshot.facts(ALL_FACT_KINDS)) {
+        const fact = scan.factRow(context, row);
+        if (!fact) continue;
+        present.get(row.kind)?.add(row.key);
+        if (row.kind === 'delivery') for (const stream of fact.streams || []) present.get('stream').add(stream.key);
+      }
+      for (const kind of REMOVABLE_KINDS) {
+        for (const entity of store.entities(`fact:${kind}:`)) {
+          const key = entity.slice(`fact:${kind}:`.length);
+          if (!present.get(kind).has(key)) scan.factRemoved(context, kind, key);
+        }
+      }
+      return context.report;
+    },
+  };
+}

package/src/runner/lease.js

@@ -0,0 +1,46 @@
+/**
+ * The runner process's view of the person's manager lease (Q9). The daemon claims it in the cloud and reports how
+ * long it may still count on it, measured from when it asked; this process turns that into a deadline on its own
+ * monotonic clock. No wall-clock time from the cloud is ever compared with this machine's (H4), and at the deadline
+ * the lease is lost here before the cloud can grant it to anyone else.
+ */
+export function createLeaseState({ monotonic = () => performance.now(), log = () => {} } = {}) {
+  let held = false;
+  let deadline = 0;
+  let view = { holder: null, here: false, fence: 0 };
+  let timer = null;
+  const listeners = new Set();
+  const set = (next) => {
+    if (next === held) return;
+    held = next;
+    log(next ? 'lease_held' : 'lease_lost', { fence: view.fence, holder: view.holder });
+    for (const fn of listeners) fn(held);
+  };
+  const live = () => held && monotonic() < deadline;
+  return {
+    held: () => {
+      if (held && !live()) set(false);
+      return held;
+    },
+    view: () => ({ ...view, here: live() }),
+    onChange: (fn) => listeners.add(fn),
+    /** What the daemon measured: `{ held, remainingMs, holder, fence }`. */
+    report({ held: claimed, remainingMs = 0, holder = null, fence = 0 }) {
+      view = { holder, here: Boolean(claimed), fence };
+      clearTimeout(timer);
+      if (claimed && remainingMs > 0) {
+        deadline = monotonic() + remainingMs;
+        timer = setTimeout(() => set(false), remainingMs);
+        timer.unref?.();
+        set(true);
+      } else {
+        deadline = 0;
+        set(false);
+      }
+    },
+    close() {
+      clearTimeout(timer);
+      set(false);
+    },
+  };
+}

package/src/runner/main.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// The Pulse runner process: the hub core over runner.db and the facade on 127.0.0.1. The daemon starts it with
+// PULSE_HUB_HOME and PULSE_RUNNER_DB set and one --config file; cloud traffic stays in the daemon (it owns the
+// tokens) and reaches this process over the IPC channel (see bridge.js).
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { hubHome, runnerDb } from '../hub/home.mjs';
+import { tokenPath } from '../hub/core/auth.mjs';
+import { startRunner } from './runnerProcess.js';
+
+function configFrom(argv) {
+  const index = argv.indexOf('--config');
+  if (index === -1 || !argv[index + 1]) throw new Error('usage: main.js --config <runner.json>');
+  return JSON.parse(readFileSync(path.resolve(argv[index + 1]), 'utf8'));
+}
+
+const fail = (code, message) => {
+  process.stderr.write(`Pulse runner refused to start: ${code}: ${message}\n`);
+  process.exit(78);
+};
+
+let config;
+try { config = configFrom(process.argv.slice(2)); } catch (error) { fail('bad_config', error.message); }
+const home = hubHome();
+try {
+  // The facade answers with the token every agent already holds; a missing token is never replaced by a new one.
+  readFileSync(tokenPath(path.join(home, 'state')), 'utf8');
+} catch {
+  fail('no_hub_token', `${tokenPath(path.join(home, 'state'))} is missing`);
+}
+
+startRunner({ ...config, hubHome: home, dbFile: runnerDb() }).catch((error) => {
+  process.stderr.write(`Pulse runner failed: ${error.code || 'runner_failed'}: ${error.stack || error.message}\n`);
+  process.exit(1);
+});

package/src/runner/render.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { decisionPost } from '../hub/lib/channels.mjs';
+import { splitPosts } from '../lib/channelScanner.js';
+import { appendNoFollow, channelFileFor } from './facade.js';
+
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+
+/** The block a post appends: its own header and body when it carries one, else a USER post as the hub writes them. */
+function blockOf(payload) {
+  const body = String(payload.body || '').replace(/\r/g, '').trimEnd();
+  if (/^## \[[A-Z][A-Z0-9 -]*\] /.test(body)) return body;
+  return decisionPost(body, { kind: payload.type || 'MESSAGE' }).trim();
+}
+
+/**
+ * The channel bridge's render side (design §4.6): a post that reached Pulse from elsewhere is appended to this
+ * machine's channel.md once, never rewritten. Each one goes through `pending` (recorded first), the append, then
+ * `done` together with the Phase 2 ingest record of the block it became, so the channel scanner never sends it back
+ * as this machine's own post (M3). A restart finishes what was pending: it appends only if the block isn't there.
+ */
+export function createRenderer({ runner, roots, now = Date.now, log = () => {} }) {
+  const { db } = runner.hub;
+  const q = {
+    get: db.prepare('SELECT post_key, channel, file, text, state FROM pulse_rendered WHERE post_key = ?'),
+    pending: db.prepare("SELECT post_key, channel, file, text FROM pulse_rendered WHERE state = 'pending' ORDER BY at"),
+    record: db.prepare('INSERT OR IGNORE INTO pulse_rendered (post_key, channel, file, text, state, at) VALUES (?, ?, ?, ?, ?, ?)'),
+    done: db.prepare("UPDATE pulse_rendered SET state = ? WHERE post_key = ?"),
+  };
+
+  /** Where the block landed in the file: its ordinal and the scanner's id for it (digest of the block, occurrence). */
+  function locate(file, text) {
+    const content = readFileSync(file, 'utf8');
+    const posts = splitPosts(content, statSync(file).mtimeMs);
+    const seen = new Map();
+    let found = null;
+    posts.forEach((post, ordinal) => {
+      const digest = sha(post.text).slice(0, 16);
+      const n = seen.get(digest) || 0;
+      seen.set(digest, n + 1);
+      if (post.text === text) found = { ordinal, id: `${digest}:${n}`, at: post.at };
+    });
+    return found;
+  }
+
+  function finish(row) {
+    let place = locate(row.file, row.text);
+    if (!place) {
+      const content = readFileSync(row.file, 'utf8');
+      appendNoFollow(row.file, `${content.endsWith('\n') ? '\n' : '\n\n'}${row.text}\n`);
+      place = locate(row.file, row.text);
+    }
+    if (!place) throw new Error('the appended block is not where it was written');
+    runner.capture.applying(() => {
+      runner.store.setIngested(row.channel, { ordinal: place.ordinal, sha: place.id, postKey: row.post_key, at: place.at });
+      q.done.run('done', row.post_key);
+    });
+  }
+
+  return {
+    /** Remote `post.created` events the applier accepted, in seq order. */
+    render(events) {
+      let rendered = 0;
+      for (const event of events) {
+        const p = event.payload || {};
+        const channel = String(p.channel || '');
+        const key = channel.startsWith('task:') ? channel.slice(5) : null;
+        if (q.get.get(event.key)) continue;
+        const file = key ? channelFileFor(key, roots) : null;
+        const text = blockOf(p);
+        q.record.run(event.key, channel, file, text, file ? 'pending' : 'no_local_channel', now());
+        if (!file) continue;
+        try {
+          finish({ post_key: event.key, channel, file, text });
+          rendered += 1;
+        } catch (error) {
+          log('render_failed', { channel, code: error.code || 'error', message: String(error.message).slice(0, 200) });
+        }
+      }
+      return rendered;
+    },
+    /** At start: finish every render a crash left pending. */
+    resume() {
+      let finished = 0;
+      for (const row of q.pending.all()) {
+        try { finish(row); finished += 1; } catch (error) { log('render_failed', { channel: row.channel, code: error.code || 'error' }); }
+      }
+      return finished;
+    },
+  };
+}

package/src/runner/runnerChild.js

@@ -0,0 +1,57 @@
+import { fork } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MAIN = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
+
+/**
+ * The runner process, started by the daemon (or a test) with its hub and runner.db, and an IPC channel for what
+ * needs the cloud: sync pages to apply, the manager lease, held credentials to scrub. `request` sends one message
+ * and resolves with the runner's reply to it.
+ */
+export function forkRunner({ hubHome, dbFile, configFile, env = {}, execPath = process.execPath, execArgv = [], stdio = ['ignore', 'pipe', 'pipe', 'ipc'] }) {
+  const child = fork(MAIN, ['--config', configFile], {
+    env: { ...process.env, ...env, PULSE_HUB_HOME: hubHome, PULSE_RUNNER_DB: dbFile },
+    execPath, execArgv, stdio, serialization: 'advanced',
+  });
+  let counter = 0;
+  const waiting = new Map();
+  const listeners = new Map();
+  child.on('message', (message) => {
+    if (message?.type === 'reply' && waiting.has(message.id)) {
+      const { resolve, reject } = waiting.get(message.id);
+      waiting.delete(message.id);
+      if (message.error) reject(Object.assign(new Error(message.error.message), { code: message.error.code }));
+      else resolve(message.result);
+      return;
+    }
+    for (const fn of listeners.get(message?.type) || []) fn(message);
+  });
+  child.once('exit', (code, signal) => {
+    for (const { reject } of waiting.values()) reject(Object.assign(new Error(`runner exited (${signal || code})`), { code: 'runner_exited' }));
+    waiting.clear();
+  });
+  const ready = new Promise((resolve, reject) => {
+    const on = (message) => { if (message?.type === 'ready') { child.off('message', on); resolve(message); } };
+    child.on('message', on);
+    child.once('exit', (code, signal) => reject(Object.assign(new Error(`runner exited before it was ready (${signal || code})`), { code: 'runner_exited' })));
+  });
+  ready.catch(() => {});
+  return {
+    child,
+    ready,
+    send: (message) => child.connected && child.send(message),
+    request(message) {
+      const id = (counter += 1);
+      return new Promise((resolve, reject) => {
+        waiting.set(id, { resolve, reject });
+        if (!child.connected) { waiting.delete(id); reject(Object.assign(new Error('runner not connected'), { code: 'runner_exited' })); return; }
+        child.send({ ...message, id });
+      });
+    },
+    on(type, fn) {
+      if (!listeners.has(type)) listeners.set(type, new Set());
+      listeners.get(type).add(fn);
+    },
+  };
+}

package/src/runner/runnerHub.js

@@ -0,0 +1,104 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { openHub } from '../hub/core/hub.mjs';
+import { HubError } from '../lib/errors.js';
+import { OUTBOX_MAX_PENDING, RunnerStore, SEED_META } from '../lib/runnerStore.js';
+import { createCapture, installCapture } from './capture.js';
+import { installRunnerSchema } from './runnerSchema.js';
+
+/**
+ * runner.db opened as the hub: the 6b2fb0b ledger tables run the ported core unchanged, the Phase 2 outbox shares
+ * the same connection, and capture turns every local write into outbox commands in the same transaction.
+ */
+/** The hub ledger tables a cutover seed copies from hub.db.pre-cutover, rowids kept; leases stay with the old hub. */
+const SEEDED_TABLES = ['actors', 'presence', 'messages', 'deliveries', 'events', 'quarantine', 'facts', 'imports', 'settings'];
+/** Children first, so a reseed's deletes never trip the hub's foreign keys. */
+const CLEARED_TABLES = ['deliveries', 'presence', 'messages', 'actors', 'events', 'quarantine', 'facts', 'imports', 'settings'];
+/**
+ * What the runner applied on top of a seed, cleared with it: a reseed leaves runner.db as a first cutover from that
+ * backup finds it. Phase 2's tables (outbox, sent from the import and capture, dead, cursor, version, ingested) stay,
+ * and so do the records of effects outside runner.db that must not repeat: pulse_spool, pulse_rendered, pulse_jobs_local.
+ */
+const RESEED_RESETS = [
+  'DELETE FROM leases',
+  'DELETE FROM pulse_capture',
+  'DELETE FROM pulse_events',
+  'DELETE FROM pulse_quarantine',
+  'DELETE FROM pulse_deferred',
+  'DELETE FROM pulse_fence',
+  'DELETE FROM pulse_registered',
+  "DELETE FROM sent WHERE source = 'sync'",
+  'UPDATE pulse_sync SET applied_seq = 0, head = 0, floor = 0, presence_stamp = 0, last_ok_at = NULL, last_error = NULL, resync = NULL WHERE one = 1',
+];
+
+const sha256Of = async (file) => createHash('sha256').update(await readFile(file)).digest('hex');
+
+/**
+ * Copy the old hub's rows into runner.db, with capture off: Pulse already has them (the import). The copy is keyed to
+ * the backup's sha256: the same backup is copied once; another backup, or one a rollback marked, replaces the hub
+ * tables and the sync state built on them (B1). ATTACH can't run inside a transaction, so the copy runs in `applying`
+ * between the attach and the detach.
+ */
+function seedFrom(db, store, capture, { file, sha256 }) {
+  const previous = store.meta(SEED_META);
+  if (previous?.sha256 === sha256 && !previous.rolledBackAt) return null;
+  db.prepare('ATTACH DATABASE ? AS seed').run(file);
+  try {
+    return capture.applying(() => {
+      if (previous) {
+        for (const table of CLEARED_TABLES) db.prepare(`DELETE FROM main.${table}`).run();
+        for (const sql of RESEED_RESETS) db.prepare(sql).run();
+      }
+      const counts = {};
+      for (const table of SEEDED_TABLES) {
+        const columns = db.prepare(`SELECT name FROM pragma_table_info('${table}')`).all().map((c) => c.name).join(', ');
+        counts[table] = Number(db.prepare(`INSERT OR IGNORE INTO main.${table} (rowid, ${columns}) SELECT rowid, ${columns} FROM seed.${table}`).run().changes);
+      }
+      store.setMeta(SEED_META, {
+        file, sha256, at: Date.now(), counts,
+        ...(previous ? { previous: { file: previous.file, sha256: previous.sha256 ?? null, rolledBackAt: previous.rolledBackAt ?? null } } : {}),
+      });
+      return { counts, reseeded: Boolean(previous) };
+    });
+  } finally {
+    db.prepare('DETACH DATABASE seed').run();
+  }
+}
+
+export async function openRunnerHub({ directory, stateDir, mapping, now = Date.now, maxPending = OUTBOX_MAX_PENDING, log, seed = null, seedSha256 = null }) {
+  const seedSha = seed ? await sha256Of(seed) : null;
+  if (seed && seedSha256 && seedSha !== seedSha256) {
+    throw new HubError('HUB_RUNNER_SEED_MISMATCH', `${seed} is not the backup the cutover recorded (sha256 ${seedSha.slice(0, 12)}, expected ${seedSha256.slice(0, 12)})`);
+  }
+  const init = await RunnerStore.open(directory, { now, maxPending });
+  const { file } = init;
+  init.close();
+  const hub = openHub(stateDir, file);
+  installCapture(hub.db);
+  installRunnerSchema(hub.db);
+  const store = new RunnerStore({ db: hub.db, file, now, maxPending });
+  const mapped = typeof mapping === 'function' ? mapping(store) : mapping;
+  const capture = createCapture({ db: hub.db, store, mapping: mapped, log });
+  if (seed) {
+    const seeded = seedFrom(hub.db, store, capture, { file: seed, sha256: seedSha });
+    if (seeded) log?.('runner_seeded', { from: seed, sha256: seedSha, ...seeded });
+  }
+  // Rows written before the triggers existed (openHub's own `user` and `manager`, a seed) are picked up once here.
+  // A full outbox (pulse_backlog) must not stop the runner from starting (I4); the pump and the next sweep go on.
+  if (mapped.sweep) {
+    try { capture.tx(() => mapped.sweep(hub.db), { label: 'capture sweep at open' }); } catch (error) {
+      if (error.code !== 'pulse_backlog') throw error;
+      log?.('capture_backlog', { at: 'open' });
+    }
+  }
+  return {
+    hub,
+    store,
+    capture,
+    mapping: mapped,
+    file,
+    close() {
+      hub.db.close();
+    },
+  };
+}

package/src/runner/runnerProcess.js

@@ -0,0 +1,124 @@
+import { mkdirSync, watch } from 'node:fs';
+import path from 'node:path';
+import { RUNNER_DB_FILE } from '../lib/runnerStore.js';
+import { createApplier } from './applier.js';
+import { createLeaseState } from './lease.js';
+import { createRenderer } from './render.js';
+import { mappingFor } from './captureMapping.js';
+import { serve } from './facade.js';
+import { openRunnerHub } from './runnerHub.js';
+import { importSpool } from './spool.js';
+
+const PUMP_MS = 250;
+const SPOOL_SCAN_MS = 5000;
+/** Actors coalesced by capture (a clock-only change goes up at most once a minute) and dropped facts. */
+const SWEEP_MS = 30_000;
+
+/** Runs the runner in this process: runner.db as the hub, capture, the facade. Resolves once it is listening. */
+export async function startRunner({
+  hubHome, dbFile, port = 8890, host = '127.0.0.1', mapping = 'hub', channelRoots, approvedRoots = [], transcriptsDir, enableCollector = true,
+  enableManager = true, pulseUrl = null, hookBudgetMs, writeBudgetMs, machineId = null, cutoverSeq = 0, lease: leaseMode = 'cloud', managerOptions, maxPending,
+  seedFrom = null, seedSha256 = null, workspaceRoot = path.dirname(hubHome), discipline, send = process.send ? (message) => process.send(message) : null, log = (event, details) => {
+    process.stdout.write(`${JSON.stringify({ event, at: new Date().toISOString(), ...details })}\n`);
+  },
+}) {
+  if (path.basename(dbFile) !== RUNNER_DB_FILE) throw new Error(`the runner database must be named ${RUNNER_DB_FILE}`);
+  const stateDir = path.join(hubHome, 'state');
+  // The values capture scrubs besides its secret rules: the hub token, and the daemon's held credentials (IPC).
+  let heldSecrets = [];
+  let hubToken = null;
+  const roots = channelRoots || ['AgentPulseApps', 'Google_Cloud'].map((dir) => path.join(path.dirname(hubHome), dir));
+  const runner = await openRunnerHub({
+    directory: path.dirname(dbFile), stateDir, log, seed: seedFrom, seedSha256, ...(maxPending ? { maxPending } : {}),
+    mapping: mappingFor(mapping, { hubDir: hubHome, roots, approvedRoots, secrets: () => [hubToken, ...heldSecrets] }),
+  });
+  hubToken = runner.hub.token;
+  const applier = createApplier({ runner, machineId, cutoverSeq: () => cutoverSeq, log });
+  const renderer = createRenderer({ runner, roots, log });
+  renderer.resume();
+  /** What the daemon last measured (§9.4); the facade shows it. Until the first report the runner is starting. */
+  let health = { state: 'starting', reason: 'waiting for the first sync' };
+  // With a daemon, the manager waits for the cloud lease; alone (no IPC), this runner is the only one, as the hub was.
+  const lease = send && leaseMode === 'cloud' ? createLeaseState({ log }) : null;
+  const handlers = {
+    apply: (message) => {
+      const result = applier.apply(message.page);
+      const rendered = result.posts.length ? renderer.render(result.posts) : 0;
+      if (result.applied) onWrite();
+      return { ...result, posts: result.posts.length, rendered };
+    },
+    retryDeferred: () => applier.retryDeferred(),
+    health: (message) => { health = message.health; return null; },
+    lease: (message) => { lease?.report(message); return lease ? lease.view() : null; },
+    secrets: (message) => { heldSecrets = (message.values || []).filter((v) => typeof v === 'string' && v); return null; },
+    ping: () => ({ pid: process.pid }),
+  };
+  if (send) {
+    process.on('message', (message) => {
+      const handler = handlers[message?.type];
+      if (!handler) return;
+      let reply;
+      try {
+        reply = { type: 'reply', id: message.id, result: handler(message) };
+      } catch (error) {
+        log('ipc_failed', { type: message.type, code: error.code || 'error', message: String(error.message).slice(0, 200) });
+        reply = { type: 'reply', id: message.id, error: { code: error.code || 'runner_error', message: String(error.message).slice(0, 300) } };
+      }
+      if (message.id !== undefined) send(reply);
+    });
+  }
+  let wroteTimer = null;
+  const onWrite = () => {
+    if (!send || wroteTimer) return;
+    wroteTimer = setTimeout(() => { wroteTimer = null; send({ type: 'wrote' }); }, 20);
+  };
+  const facade = serve({
+    hub: runner.hub, capture: runner.capture, port, listenHost: host, stateDir, dbFile, enableCollector, enableManager,
+    pulseUrl, onWrite, health: () => health, ...(lease ? { lease } : {}), ...(managerOptions ? { managerOptions } : {}), ...(hookBudgetMs !== undefined ? { hookBudgetMs } : {}), ...(writeBudgetMs !== undefined ? { writeBudgetMs } : {}),
+    channelRoots: roots, workspaceRoot, ...(discipline ? { discipline } : {}), ...(transcriptsDir !== undefined ? { transcriptsDir } : {}),
+  });
+  const pump = setInterval(() => {
+    try { if (runner.capture.pump()) onWrite(); } catch (error) { log('capture_pump_failed', { code: error.code || 'error', message: String(error.message).slice(0, 200) }); }
+  }, PUMP_MS);
+  pump.unref();
+  const sweep = setInterval(() => {
+    try { runner.capture.tx(() => runner.mapping.sweep(runner.hub.db), { label: 'capture sweep' }); onWrite(); } catch (error) { log('capture_sweep_failed', { code: error.code || 'error', message: String(error.message).slice(0, 200) }); }
+  }, SWEEP_MS);
+  sweep.unref();
+  const spoolDir = path.join(stateDir, 'spool');
+  mkdirSync(spoolDir, { recursive: true, mode: 0o700 });
+  const drainSpool = () => {
+    try {
+      const { imported } = importSpool({ hub: runner.hub, capture: runner.capture, spoolDir, log });
+      if (imported) { log('spool_imported', { imported }); onWrite(); }
+    } catch (error) { log('spool_import_failed', { code: error.code || 'error', message: String(error.message).slice(0, 200) }); }
+  };
+  drainSpool();
+  const spoolWatch = watch(spoolDir, () => drainSpool());
+  spoolWatch.on('error', () => {});
+  const spoolScan = setInterval(drainSpool, SPOOL_SCAN_MS);
+  spoolScan.unref();
+  await new Promise((resolve, reject) => {
+    facade.server.once('listening', resolve);
+    facade.server.once('error', reject);
+  });
+  const address = facade.server.address();
+  log('runner_ready', { port: address.port, pid: process.pid });
+  if (send) send({ type: 'ready', port: address.port, pid: process.pid });
+  let closing = false;
+  const close = () => {
+    if (closing) return;
+    closing = true;
+    clearInterval(pump);
+    clearInterval(sweep);
+    clearInterval(spoolScan);
+    spoolWatch.close();
+    facade.server.close();
+    facade.server.closeAllConnections?.();
+    try { runner.capture.pump(); } catch { /* the journal stays for the next start */ }
+    runner.close();
+  };
+  process.once('SIGTERM', () => { close(); process.exit(0); });
+  process.once('SIGINT', () => { close(); process.exit(0); });
+  return { runner, facade, port: address.port, close };
+}