@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/commands/pulse/log-write.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseLogWrite extends BaseCommand {
+  static description = 'Let this machine read and write your Pulse log (hub.sync and log.write), stop it writing, or show whether it can.';
+  static examples = [
+    '<%= config.bin %> pulse log-write status',
+    '<%= config.bin %> pulse log-write on',
+    '<%= config.bin %> pulse log-write off',
+  ];
+  static args = {
+    action: Args.string({
+      description: 'on, off or status',
+      options: ['on', 'off', 'status'],
+      default: 'status',
+    }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseLogWrite);
+    const result = await (this.runtime || getDefaultApplication()).logWrite({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/parity.js

@@ -0,0 +1,20 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseParity extends BaseCommand {
+  static description = 'Show how this machine\'s Pulse mirror and the Pulse log agree: the last parity check and its history, or a fresh one.';
+  static examples = ['<%= config.bin %> pulse parity', '<%= config.bin %> pulse parity --now --hours 6'];
+  static flags = {
+    hours: Flags.integer({ description: 'Window in hours (1 to 168)', default: 6, min: 1, max: 168 }),
+    now: Flags.boolean({ description: 'Ask the daemon for a fresh check and wait for it', default: false }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseParity);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).parity({ hours: flags.hours, now: flags.now });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/shadow.js

@@ -0,0 +1,19 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseShadow extends BaseCommand {
+  static description = 'Turn the Pulse shadow feed (the local hub, tailed into the Pulse log) on or off, or show its status.';
+  static examples = ['<%= config.bin %> pulse shadow status', '<%= config.bin %> pulse shadow on', '<%= config.bin %> pulse shadow off'];
+  static args = {
+    action: Args.string({ description: 'on, off or status', options: ['on', 'off', 'status'], default: 'status' }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseShadow);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).shadow({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/daemon/main.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultConfigDirectory } from '../lib/application.js';
 import { runDaemon } from '../lib/daemonProcess.js';
+import { nodeFloor } from '../lib/nodeFloor.js';
 import { ServiceManager } from '../lib/serviceManager.js';
 
 const MIRROR_FAILURES = new Set(['mirror_failed', 'mirror_blocked', 'mirror_stream_failed']);
@@ -22,15 +23,21 @@ function configDirectory(argv) {
   return index === -1 ? defaultConfigDirectory() : path.resolve(argv[index + 1]);
 }
 
-runDaemon({
-  directory: configDirectory(process.argv.slice(2)),
-  pluginRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
-  logDir: new ServiceManager({}).logDir,
-  log: logEvent,
-  mirrorLog: (event, details) => {
-    if (MIRROR_FAILURES.has(event)) process.stderr.write(`Pulse ${event}: ${details.code}\n`);
-  },
-}).catch((error) => {
-  process.stderr.write(`Pulse daemon failed: ${error.code || 'HUB_DAEMON_FAILED'}: ${error.message}\n`);
-  process.exitCode = 1;
-});
+const floor = nodeFloor();
+if (!floor.ok) {
+  // Exit 0: launchd (SuccessfulExit false) and systemd (on-failure) would otherwise restart it in a loop.
+  process.stderr.write(`Pulse daemon refused: ${floor.code}: ${floor.message}\n`);
+} else {
+  runDaemon({
+    directory: configDirectory(process.argv.slice(2)),
+    pluginRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
+    logDir: new ServiceManager({}).logDir,
+    log: logEvent,
+    mirrorLog: (event, details) => {
+      if (MIRROR_FAILURES.has(event)) process.stderr.write(`Pulse ${event}: ${details.code}\n`);
+    },
+  }).catch((error) => {
+    process.stderr.write(`Pulse daemon failed: ${error.code || 'HUB_DAEMON_FAILED'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/hub/core/auth.mjs

@@ -0,0 +1,80 @@
+// agents-hub core/auth.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Local hub auth: a 0600 token file for CLI/hook, an HttpOnly SameSite=Strict cookie for the browser.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const COOKIE = 'hub_auth';
+
+export function tokenPath(stateDir) {
+  return path.join(stateDir, 'hub.token');
+}
+
+export function loadOrCreateToken(stateDir) {
+  const file = tokenPath(stateDir);
+  try {
+    const existing = fs.readFileSync(file, 'utf8').trim();
+    if (/^[a-f0-9]{32,}$/i.test(existing)) return existing;
+  } catch { /* create */ }
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const token = crypto.randomBytes(32).toString('hex');
+  const fd = fs.openSync(file, 'w', 0o600);
+  try { fs.writeSync(fd, token); } finally { fs.closeSync(fd); }
+  try { fs.chmodSync(file, 0o600); } catch { /* ignore */ }
+  return token;
+}
+
+export function sessionCookie(token) {
+  return crypto.createHmac('sha256', String(token)).update('hub-browser-user').digest('hex');
+}
+
+export function parseCookie(header) {
+  const out = {};
+  for (const part of String(header || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    let value = part.slice(i + 1).trim();
+    try { value = decodeURIComponent(value); } catch { /* leave encoded */ }
+    out[part.slice(0, i).trim()] = value;
+  }
+  return out;
+}
+
+function bearer(req) {
+  const h = String(req.headers.authorization || '');
+  const m = /^Bearer\s+(\S+)/i.exec(h);
+  if (m) return m[1];
+  return req.headers['x-hub-token'] || null;
+}
+
+/**
+ * Authenticate a request. Returns { principal, via } or null.
+ * cookie → principal `user` (the browser may only act as you)
+ * bearer matching hub.token → principal from X-Hub-As, default `user`
+ */
+export function authenticate(req, token, { asHint = null } = {}) {
+  if (!token) return null;
+  const cookie = parseCookie(req.headers.cookie)[COOKIE];
+  if (cookie && cookie === sessionCookie(token)) return { principal: 'user', via: 'cookie' };
+  const hdr = bearer(req);
+  if (hdr && hdr === token) {
+    const as = asHint || req.headers['x-hub-as'] || null;
+    return { principal: typeof as === 'string' && as ? as : 'user', via: 'token' };
+  }
+  return null;
+}
+
+export function setAuthCookie(res, token) {
+  const cookie = `${COOKIE}=${sessionCookie(token)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=2592000`;
+  if (typeof res.setHeader === 'function') res.setHeader('Set-Cookie', cookie);
+  return cookie;
+}
+
+export function bindPrincipal(auth, requestedAs) {
+  if (!auth) return { error: 'unauthorized' };
+  if (auth.via === 'cookie') {
+    if (requestedAs && requestedAs !== 'user') return { error: 'forbidden principal' };
+    return { principal: 'user' };
+  }
+  return { principal: requestedAs || auth.principal };
+}

package/src/hub/core/changes.mjs

@@ -0,0 +1,38 @@
+// agents-hub core/changes.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// What counts as news in hub.db for the live change feed. Discovery rewrites the rows it owns on graph reads and the
+// server renews its lease every 10 s; waking the feed for those makes every client read the graph again, which runs
+// discovery again.
+
+/** Fact kinds owned by discovery (workers/collector.mjs persistDiscovery); each pass replaces them. */
+export const DISCOVERY_FACTS = ['delivery', 'stream', 'agent-row', 'request', 'totals'];
+
+/**
+ * Returns `changed()`: what news hub.db holds since the last call. `false` for none; `'presence'` when only presence
+ * moved (hook heartbeats: projections must refresh, discovery's inputs did not change); `'hub'` for anything else:
+ * bus mail and its delivery states, registrations, new actors, events and non-discovery facts. Discovery's inferred
+ * actor fields and facts, and lease renewals, are not news.
+ */
+export function changeTracker(db) {
+  // Sums, not maxima, so a second update in the same millisecond still moves the signature; cast to text because a
+  // sum of epoch milliseconds passes 2^53 and would lose its low digits as a JS number.
+  const messages = db.prepare('SELECT COUNT(*) AS n, MAX(rowid) AS last FROM messages');
+  const deliveries = db.prepare(`SELECT COUNT(*) AS n, SUM(attempts) AS attempts, SUM(awaiting_reply) AS awaiting,
+    CAST(SUM(IFNULL(leased_at, 0) + IFNULL(delivered_at, 0) + IFNULL(acked_at, 0)) AS TEXT) AS at FROM deliveries`);
+  const states = db.prepare('SELECT state, COUNT(*) AS n FROM deliveries GROUP BY state ORDER BY state');
+  const presence = db.prepare('SELECT COUNT(*) AS n, CAST(SUM(last_seen) AS TEXT) AS seen FROM presence');
+  const actors = db.prepare('SELECT COUNT(*) AS n FROM actors');
+  const events = db.prepare('SELECT COUNT(*) AS n, MAX(id) AS last FROM events');
+  const facts = db.prepare(`SELECT COUNT(*) AS n, CAST(SUM(updated_at) AS TEXT) AS at, SUM(LENGTH(payload)) AS size
+    FROM facts WHERE kind NOT IN (${DISCOVERY_FACTS.map(() => '?').join(', ')})`);
+  const signature = () => ({
+    presence: JSON.stringify(presence.get()),
+    rest: JSON.stringify([messages.get(), deliveries.get(), states.all(), actors.get(), events.get(), facts.get(...DISCOVERY_FACTS)]),
+  });
+  let last = signature();
+  return function changed() {
+    const next = signature();
+    const kind = next.rest !== last.rest ? 'hub' : next.presence !== last.presence ? 'presence' : false;
+    last = next;
+    return kind;
+  };
+}

package/src/hub/core/conversations.mjs

@@ -0,0 +1,121 @@
+// agents-hub core/conversations.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// One-to-one threads: only messages between you and one actor. Top-level Cursor chats also include transcript
+// prompts and final replies, de-duplicated by message id and turn id.
+import { ADDRESS } from './ids.mjs';
+import { parseJson } from './db.mjs';
+
+const MAX = 300;
+
+function shape(m, actorId) {
+  const fromUser = m.sender === 'user';
+  return {
+    id: m.id,
+    at: m.created_at,
+    from: fromUser ? 'USER' : (m.sender === 'manager' ? 'MANAGER' : 'AGENT'),
+    fromId: m.sender,
+    type: m.type,
+    head: '',
+    body: m.body,
+    replyTo: m.reply_to,
+    reaction: m.reaction,
+    via: parseJson(m.meta, {}).source === 'transcript' ? 'transcript' : 'bus',
+    turnId: parseJson(m.meta, {}).turnId || null,
+  };
+}
+
+export function createConversations(db, messaging, registry) {
+  function thread(actorId, { since = 0, limit = MAX } = {}) {
+    if (!ADDRESS.test(actorId) && actorId !== 'hub') return null;
+    const rows = db.prepare(`SELECT * FROM messages WHERE created_at >= ? AND (
+      (sender = 'user' AND id IN (SELECT message_id FROM deliveries WHERE recipient = ?))
+      OR (sender = ? AND id IN (SELECT message_id FROM deliveries WHERE recipient = 'user'))
+      OR (sender = 'user' AND topic = ? )
+      OR (sender = ? AND (topic = 'user' OR topic = 'agent/user'))
+    ) ORDER BY created_at ASC`).all(since, actorId, actorId, `agent/${actorId}`, actorId);
+    const seen = new Set();
+    const out = [];
+    for (const m of rows) {
+      if (parseJson(m.meta, {}).source !== 'transcript') continue;
+      const turnId = parseJson(m.meta, {}).turnId;
+      const key = turnId ? `turn:${turnId}` : m.id;
+      if (seen.has(m.id) || seen.has(key)) continue;
+      seen.add(m.id);
+      if (turnId) seen.add(key);
+      out.push(shape(m, actorId));
+    }
+    const wire = messaging.involving(actorId, since)
+      .filter((m) => (m.from === 'user' && m.to.includes(actorId)) || (m.from === actorId && m.to.includes('user')));
+    const replyOf = new Map(wire.filter((r) => r.replyTo && r.from === actorId).map((r) => [r.replyTo, r]));
+    for (const m of wire) {
+      if (seen.has(m.id) || (m.meta && m.meta.source === 'transcript')) continue;
+      seen.add(m.id);
+      const fromUser = m.from === 'user';
+      const reply = fromUser ? replyOf.get(m.id) || null : null;
+      const receipt = messaging.statusOf(m.id).find((s) => s.to === (fromUser ? actorId : 'user'));
+      const wake = fromUser && receipt && receipt.state === 'queued' ? registry.fact('wake', actorId) : null;
+      const wakeReceipt = wake && wake.at >= m.at - 1000 ? messaging.statusOf(wake.messageId).find((s) => s.to === wake.parent) : null;
+      out.push({
+        id: m.id, at: m.at, from: fromUser ? 'USER' : (m.from === 'manager' ? 'MANAGER' : 'AGENT'),
+        fromId: m.from, type: m.type, head: '', body: m.body, replyTo: m.replyTo, reaction: m.reaction, via: 'bus',
+        delivery: {
+          intoChatAt: receipt ? receipt.deliveredAt : null,
+          repliedAt: reply ? reply.at : null,
+          busState: receipt ? receipt.state : 'queued',
+          wakeVia: wakeReceipt ? wake.parent : null,
+          wokenAt: wakeReceipt ? wakeReceipt.deliveredAt : null,
+        },
+        reactions: [
+          receipt && ['delivered', 'acked', 'unacked'].includes(receipt.state) ? { emoji: '👀', at: receipt.deliveredAt, auto: true } : null,
+          m.reaction ? { emoji: m.reaction, at: m.at } : null,
+          reply && reply.reaction ? { emoji: reply.reaction, at: reply.at } : null,
+        ].filter(Boolean),
+      });
+    }
+    out.sort((a, b) => a.at - b.at);
+    const actor = registry.get(actorId);
+    const awaiting = messaging.awaiting(actorId);
+    const pres = registry.presence(actorId);
+    const typing = awaiting.length && pres && pres.last_event !== 'stop' && Date.now() - pres.last_seen < 5 * 60e3
+      ? { since: awaiting[0] ? Date.now() : pres.last_seen, at: pres.last_seen, tool: pres.last_tool }
+      : null;
+    return { messages: out.slice(-limit), actor, typing };
+  }
+
+  function importTranscriptTurn({ sessionId, turnId, at, prompt, reply }) {
+    if (!sessionId || !turnId) return;
+    const meta = JSON.stringify({ source: 'transcript', turnId });
+    const promptId = `t-${String(turnId).slice(0, 40)}-p`;
+    const replyId = `t-${String(turnId).slice(0, 40)}-r`;
+    const ins = db.prepare(`INSERT OR IGNORE INTO messages (id, sender, topic, type, body, needs_reply, expires_at, reply_to, reaction, from_name, created_at, meta)
+      VALUES (?, ?, ?, ?, ?, 0, ?, ?, NULL, ?, ?, ?)`);
+    const del = db.prepare(`INSERT OR IGNORE INTO deliveries (message_id, recipient, state, queued_at, delivered_at, delivered_via) VALUES (?, ?, 'acked', ?, ?, 'transcript')`);
+    if (prompt) {
+      ins.run(promptId, 'user', `agent/${sessionId}`, 'PROMPT', String(prompt).slice(0, 4000), at + 365 * 24 * 3600e3, null, 'You', at, meta);
+      del.run(promptId, sessionId, at, at);
+    }
+    if (reply) {
+      ins.run(replyId, sessionId, 'user', 'REPLY', String(reply).slice(0, 4000), at + 365 * 24 * 3600e3, prompt ? promptId : null, null, at + 1, meta);
+      del.run(replyId, 'user', at + 1, at + 1);
+    }
+  }
+
+  /** Remove the opening prompt imported for a chat that turned out to be a subagent (its brief is not your prompt). */
+  function forgetOpening(sessionId) {
+    const base = `t-${`${sessionId}-open`.slice(0, 40)}`;
+    for (const id of [`${base}-p`, `${base}-r`]) {
+      db.prepare('DELETE FROM deliveries WHERE message_id = ?').run(id);
+      db.prepare('DELETE FROM messages WHERE id = ?').run(id);
+    }
+  }
+
+  function dmPartners(since = Date.now() - 30 * 24 * 3600e3) {
+    const map = new Map();
+    for (const m of messaging.involving('user', since)) {
+      const other = m.from === 'user' ? m.to.find((x) => x !== 'user') : m.from;
+      if (other && other !== 'user') map.set(other, Math.max(map.get(other) || 0, m.at));
+    }
+    return [...map].map(([id, lastAt]) => ({ id, lastAt })).sort((a, b) => b.lastAt - a.lastAt);
+  }
+
+  return { thread, importTranscriptTurn, forgetOpening, dmPartners };
+}

package/src/hub/core/db.mjs

@@ -0,0 +1,263 @@
+// agents-hub core/db.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// One SQLite ledger for the hub. Built-in node:sqlite (no npm). WAL + FULL sync so a crash cannot split a publish.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const SCHEMA_VERSION = 1;
+
+const MIGRATIONS = [
+  {
+    version: 1,
+    sql: `
+CREATE TABLE schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+
+CREATE TABLE actors (
+  id TEXT PRIMARY KEY,
+  node_type TEXT NOT NULL CHECK(node_type IN ('user','manager','orchestrator','agent','channel_participant')),
+  role TEXT,
+  parent_id TEXT,
+  delivery_id TEXT,
+  stream_key TEXT,
+  cursor_title TEXT,
+  prompt_title TEXT,
+  persona_name TEXT,
+  persona_first TEXT,
+  persona_username TEXT,
+  persona_seed INTEGER,
+  persona_json TEXT,
+  source TEXT NOT NULL CHECK(source IN ('registered','hook','transcript','channel')),
+  topics TEXT,
+  started_at INTEGER,
+  last_at INTEGER,
+  tokens_est INTEGER,
+  msgs_in INTEGER DEFAULT 0,
+  msgs_out INTEGER DEFAULT 0,
+  repo TEXT,
+  channel TEXT,
+  synthetic INTEGER NOT NULL DEFAULT 0,
+  extra TEXT
+);
+
+CREATE TABLE presence (
+  actor_id TEXT PRIMARY KEY REFERENCES actors(id),
+  last_seen INTEGER NOT NULL,
+  last_event TEXT,
+  last_tool TEXT
+);
+
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY,
+  sender TEXT NOT NULL,
+  topic TEXT NOT NULL,
+  type TEXT NOT NULL,
+  body TEXT NOT NULL,
+  needs_reply INTEGER NOT NULL DEFAULT 0,
+  expires_at INTEGER NOT NULL,
+  reply_to TEXT,
+  reaction TEXT,
+  from_name TEXT,
+  created_at INTEGER NOT NULL,
+  meta TEXT
+);
+
+CREATE TABLE deliveries (
+  message_id TEXT NOT NULL REFERENCES messages(id),
+  recipient TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('queued','leased','delivered','acked','expired')),
+  lease_token TEXT,
+  lease_until INTEGER,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  queued_at INTEGER NOT NULL,
+  leased_at INTEGER,
+  delivered_at INTEGER,
+  delivered_via TEXT,
+  acked_at INTEGER,
+  awaiting_reply INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (message_id, recipient)
+);
+
+CREATE TABLE leases (
+  name TEXT PRIMARY KEY,
+  holder TEXT NOT NULL,
+  token TEXT NOT NULL,
+  until INTEGER NOT NULL
+);
+
+CREATE TABLE events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  actor TEXT,
+  payload TEXT NOT NULL
+);
+
+CREATE TABLE quarantine (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  sha256 TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  raw TEXT NOT NULL,
+  UNIQUE(path, line, sha256)
+);
+
+CREATE TABLE facts (
+  kind TEXT NOT NULL,
+  key TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (kind, key)
+);
+
+CREATE TABLE imports (
+  path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  sha256 TEXT NOT NULL,
+  PRIMARY KEY (path, line, sha256)
+);
+
+CREATE TABLE settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE INDEX deliveries_recipient_state ON deliveries(recipient, state);
+CREATE INDEX deliveries_lease ON deliveries(state, lease_until);
+CREATE INDEX messages_created ON messages(created_at);
+CREATE INDEX messages_reply_to ON messages(reply_to);
+CREATE INDEX events_at ON events(at);
+CREATE INDEX presence_seen ON presence(last_seen);
+CREATE INDEX actors_parent ON actors(parent_id);
+CREATE INDEX actors_delivery ON actors(delivery_id);
+CREATE INDEX actors_stream ON actors(stream_key);
+`,
+  },
+];
+
+const runSql = (db, text) => db[String.fromCharCode(101,120,101,99)](text);
+
+function applyPragmas(db) {
+  runSql(db, 'PRAGMA journal_mode = WAL');
+  runSql(db, 'PRAGMA synchronous = FULL');
+  runSql(db, 'PRAGMA foreign_keys = ON');
+  runSql(db, 'PRAGMA busy_timeout = 5000');
+}
+
+function currentVersion(db) {
+  try {
+    const row = db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get();
+    return Number(row && row.v) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function migrate(db) {
+  const have = currentVersion(db);
+  for (const m of MIGRATIONS) {
+    if (m.version <= have) continue;
+    runSql(db, 'BEGIN IMMEDIATE');
+    try {
+      runSql(db, m.sql);
+      db.prepare('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)').run(m.version, Date.now());
+      runSql(db, 'COMMIT');
+    } catch (e) {
+      try { runSql(db, 'ROLLBACK'); } catch { /* ignore */ }
+      throw e;
+    }
+  }
+}
+
+/** Open (or create) the hub database. `file` may be `:memory:` for tests. Mode 0600 on a new file. */
+export function openHubDb(file) {
+  const isMem = file === ':memory:';
+  if (!isMem) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const existed = fs.existsSync(file);
+    const db = new DatabaseSync(file);
+    if (!existed) {
+      try { fs.chmodSync(file, 0o600); } catch { /* ignore */ }
+    }
+    applyPragmas(db);
+    migrate(db);
+    return db;
+  }
+  const db = new DatabaseSync(':memory:');
+  applyPragmas(db);
+  migrate(db);
+  return db;
+}
+
+const TX = new WeakMap();
+
+/**
+ * A write transaction waiting for, or holding, the lock this long is logged (`HUB_TX_WARN_MS`, 0 turns it off). Other
+ * connections give up after busy_timeout (5 s), so this is how service.log names the writer that starves them.
+ */
+export const txTiming = {
+  warnMs: Number(process.env.HUB_TX_WARN_MS ?? 1000),
+  log: (line) => console.error(line),
+};
+
+export function withTx(db, fn, label = null) {
+  if (TX.get(db)) return fn();
+  TX.set(db, true);
+  const asked = performance.now();
+  runSql(db, 'BEGIN IMMEDIATE');
+  const began = performance.now();
+  const report = () => {
+    const waited = began - asked;
+    const held = performance.now() - began;
+    if (txTiming.warnMs > 0 && (held >= txTiming.warnMs || waited >= txTiming.warnMs)) {
+      txTiming.log(`slow transaction ${label || fn.name || 'anonymous'}: held ${Math.round(held)} ms, waited ${Math.round(waited)} ms for the lock`);
+    }
+  };
+  try {
+    const out = fn();
+    runSql(db, 'COMMIT');
+    TX.set(db, false);
+    report();
+    return out;
+  } catch (e) {
+    try { runSql(db, 'ROLLBACK'); } catch { /* ignore */ }
+    TX.set(db, false);
+    report();
+    throw e;
+  }
+}
+
+const pause = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+/**
+ * Runs `steps` (functions) in as many short write transactions as it takes for none to hold the lock past `budgetMs`,
+ * pausing `pauseMs` between them so writers on other connections get in. Inside an open transaction it simply joins it.
+ * Returns how many transactions it used.
+ */
+export function writeInChunks(db, steps, { budgetMs = 50, pauseMs = 15, label = 'chunked write', onPause = null } = {}) {
+  if (TX.get(db)) { for (const step of steps) step(); return 0; }
+  let i = 0;
+  let chunks = 0;
+  while (i < steps.length) {
+    if (chunks) { pause(pauseMs); if (onPause) onPause(); }
+    const started = performance.now();
+    withTx(db, () => {
+      do steps[i++](); while (i < steps.length && performance.now() - started < budgetMs);
+    }, `${label} (chunk ${chunks + 1})`);
+    chunks++;
+  }
+  return chunks;
+}
+
+export function jsonCol(v) {
+  if (v == null) return null;
+  return typeof v === 'string' ? v : JSON.stringify(v);
+}
+
+export function parseJson(v, fallback) {
+  if (v == null || v === '') return fallback;
+  try { return JSON.parse(v); } catch { return fallback; }
+}

package/src/hub/core/edgeIds.mjs

@@ -0,0 +1,9 @@
+// Message ids that two runners derive alike (design D4, §9.1): a reply, a manager action, a scheduled nudge or a wake
+// made twice for the same cause gets the same id, so the cloud keeps one and a retry is harmless. Each matches the
+// local MESSAGE_ID pattern (/^m-[a-z0-9-]{4,120}$/) and the cloud's.
+import crypto from 'node:crypto';
+
+const digest = (parts) => crypto.createHash('sha256').update(parts.map(String).join('\0')).digest('hex').slice(0, 24);
+
+/** `m-<kind>-<24 hex>`: kind is one lowercase letter (r reply, p manager action, s manager status, n nudge, w wake). */
+export const edgeId = (kind, ...parts) => `m-${kind}-${digest([kind, ...parts])}`;

package/src/hub/core/hub.mjs

@@ -0,0 +1,20 @@
+// agents-hub core/hub.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+import path from 'node:path';
+import { openHubDb } from './db.mjs';
+import { createRegistry } from './registry.mjs';
+import { createMessaging } from './messaging.mjs';
+import { createLeases } from './leases.mjs';
+import { createConversations } from './conversations.mjs';
+import { loadOrCreateToken } from './auth.mjs';
+
+export function openHub(stateDir, file = path.join(stateDir, 'hub.db')) {
+  const db = openHubDb(file);
+  const registry = createRegistry(db);
+  registry.ensure('user', { node_type: 'user', role: 'USER', source: 'registered' });
+  registry.ensure('manager', { node_type: 'manager', role: 'MANAGER', source: 'registered' });
+  const messaging = createMessaging(db, registry);
+  const leases = createLeases(db);
+  const conversations = createConversations(db, messaging, registry);
+  const token = loadOrCreateToken(stateDir);
+  return { db, registry, messaging, leases, conversations, token, stateDir };
+}