@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/hub/core/messaging.mjs

@@ -0,0 +1,322 @@
+// agents-hub core/messaging.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Transactional publish, leased claims, idempotent ack/reply, expiry. One write, all recipients, or none.
+import crypto from 'node:crypto';
+import { ADDRESS, BODY_MAX, DEFAULT_TTL_MS, LEASE_MS, MESSAGE_ID, TOPIC, TYPE } from './ids.mjs';
+import { jsonCol, parseJson, withTx } from './db.mjs';
+import { edgeId } from './edgeIds.mjs';
+
+function newId(at = Date.now()) {
+  return `m-${at.toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function envRow(r, status = null) {
+  if (!r) return null;
+  return {
+    id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+    body: r.body, text: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+    reaction: r.reaction, meta: parseJson(r.meta, {}), to: status ? status.map((s) => s.to) : parseJson(r.recipients, []),
+    status,
+  };
+}
+
+export function createMessaging(db, registry) {
+  const getMsg = db.prepare('SELECT * FROM messages WHERE id = ?');
+  const getDel = db.prepare('SELECT * FROM deliveries WHERE message_id = ? AND recipient = ?');
+  const delsOf = db.prepare('SELECT * FROM deliveries WHERE message_id = ?');
+  const byReply = db.prepare('SELECT * FROM messages WHERE reply_to = ? ORDER BY created_at ASC LIMIT 1');
+
+  /** A message published again under its edge-chosen id: the envelope as first published. */
+  function storedEnvelope(r) {
+    const to = db.prepare('SELECT recipient FROM deliveries WHERE message_id = ? ORDER BY rowid').all(r.id).map((d) => d.recipient);
+    return {
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type, body: r.body,
+      needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to, reaction: r.reaction, to, meta: parseJson(r.meta, {}),
+    };
+  }
+
+  function publish({ id: given = null, from, topic, type = 'MESSAGE', body, needsAck = false, ttlMs = DEFAULT_TTL_MS, replyTo = null, fromName = null, reaction = null, meta = {} } = {}, directory) {
+    if (!ADDRESS.test(String(from || ''))) return { error: 'bad sender' };
+    if (!TOPIC.test(String(topic || ''))) return { error: 'bad topic' };
+    if (!TYPE.test(String(type || ''))) return { error: 'bad type' };
+    if (typeof body !== 'string' || !body.trim()) return { error: 'empty body' };
+    if (given != null && !MESSAGE_ID.test(String(given))) return { error: 'bad id' };
+    const prior = given ? getMsg.get(given) : null;
+    if (prior) return prior.sender === from ? storedEnvelope(prior) : { error: 'id taken' };
+    const at = Date.now();
+    const to = directory ? resolveFromDirectory(topic, directory, from) : registry.resolveTopic(topic, from, at);
+    const id = given || newId(at);
+    const expiresAt = at + Math.max(60e3, Math.min(Number(ttlMs) || DEFAULT_TTL_MS, 7 * DEFAULT_TTL_MS));
+    const reply = typeof replyTo === 'string' && MESSAGE_ID.test(replyTo) ? replyTo : null;
+    const env = {
+      id, at, from, fromName: typeof fromName === 'string' ? fromName.slice(0, 80) : null,
+      topic, type, body: body.slice(0, BODY_MAX), needsAck: !!needsAck, expiresAt, replyTo: reply,
+      reaction: typeof reaction === 'string' ? reaction.slice(0, 16) : null, to, meta,
+    };
+    withTx(db, () => {
+      db.prepare(`INSERT INTO messages (id, sender, topic, type, body, needs_reply, expires_at, reply_to, reaction, from_name, created_at, meta)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, from, topic, type, env.body, env.needsAck ? 1 : 0, expiresAt, reply, env.reaction, env.fromName, at, jsonCol(meta));
+      const insDel = db.prepare(`INSERT INTO deliveries (message_id, recipient, state, queued_at, attempts) VALUES (?, ?, 'queued', ?, 0)`);
+      for (const r of to) insDel.run(id, r, at);
+    }, 'publish');
+    return env;
+  }
+
+  function resolveFromDirectory(topic, directory, from) {
+    const live = directory.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 = directory.find((a) => a.isArchitect && a.streams && a.streams.includes(key));
+      ids = [...crew.map((a) => a.id), ...(owner ? [owner.id] : [])];
+    } else if (topic.startsWith('delivery/')) {
+      const id = topic.slice(9);
+      ids = directory.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));
+  }
+
+  // Pending deliveries are few and found by index, their messages by primary key. Scanning `messages` instead, under the
+  // write lock, on every claim, peek and pendingCount of every connection starved the hub server past busy_timeout.
+  const PAST_DUE = `(SELECT expires_at FROM messages WHERE id = deliveries.message_id) <= ?`;
+  const expiredDue = db.prepare(`SELECT 1 FROM deliveries WHERE state IN ('queued','leased') AND ${PAST_DUE} LIMIT 1`);
+  const lapsedDue = db.prepare(`SELECT 1 FROM deliveries WHERE state = 'leased' AND lease_until IS NOT NULL AND lease_until < ? LIMIT 1`);
+
+  /** Marks expired mail and lapsed leases. Reads first: with nothing due it never takes the write lock. */
+  function expire(now = Date.now()) {
+    if (expiredDue.get(now)) {
+      db.prepare(`UPDATE deliveries SET state = 'expired', lease_token = NULL, lease_until = NULL
+        WHERE state IN ('queued','leased') AND ${PAST_DUE}`).run(now);
+    }
+    if (lapsedDue.get(now)) {
+      db.prepare(`UPDATE deliveries SET state = 'queued', lease_token = NULL, lease_until = NULL
+        WHERE state = 'leased' AND lease_until IS NOT NULL AND lease_until < ?`).run(now);
+    }
+  }
+
+  /** A reply, ack, done or status, or a reply that asks for nothing: the SQL twin of isFyi (core/ids.mjs). */
+  const FYI_SQL = `(UPPER(m.type) IN ('REPLY','ACK','DONE','STATUS') OR (m.reply_to IS NOT NULL AND m.needs_reply = 0))`;
+
+  /**
+   * Claim up to `limit` queued (or expired-lease) deliveries for `as`. Marks them leased in one transaction. With
+   * `fyiOnly`, only mail that needs no answer, so a busy worker can settle it without taking questions it cannot run.
+   */
+  function claim(as, { via = 'listen', leaseMs = LEASE_MS, limit = 1, now = Date.now(), fyiOnly = false } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    expire(now);
+    return withTx(db, () => {
+      const rows = db.prepare(`SELECT d.message_id, d.recipient, d.attempts, m.*
+        FROM deliveries d JOIN messages m ON m.id = d.message_id
+        WHERE d.recipient = ? AND (
+          d.state = 'queued'
+          OR (d.state = 'leased' AND d.lease_until < ?)
+        ) AND m.expires_at > ?${fyiOnly ? ` AND ${FYI_SQL}` : ''}
+        ORDER BY d.queued_at ASC LIMIT ?`).all(as, now, now, Math.max(1, Math.min(limit, 20)));
+      const token = crypto.randomBytes(8).toString('hex');
+      const until = now + Math.max(1, leaseMs);
+      const out = [];
+      for (const r of rows) {
+        const got = db.prepare(`UPDATE deliveries SET state = 'leased', lease_token = ?, lease_until = ?,
+          leased_at = ?, attempts = attempts + 1, delivered_via = ?
+          WHERE message_id = ? AND recipient = ? AND (state = 'queued' OR (state = 'leased' AND lease_until < ?))`)
+          .run(token, until, now, via, r.message_id, as, now);
+        if (!got || !got.changes) continue;
+        out.push({
+          id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+          text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+          reaction: r.reaction, leaseToken: token, leaseUntil: until, attempts: (Number(r.attempts) || 0) + 1,
+          meta: parseJson(r.meta, {}),
+        });
+      }
+      return out;
+    }, `claim ${as}`);
+  }
+
+  /** Look at queued mail without claiming it (postToolUse mid-turn context). */
+  function peek(as, { now = Date.now(), limit = 20 } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    expire(now);
+    return db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state = 'queued' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC LIMIT ?`).all(as, now, limit).map((r) => ({
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+      text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+      reaction: r.reaction, meta: parseJson(r.meta, {}),
+    }));
+  }
+
+  /**
+   * Back to the queue at once: everything still leased to `as`, whose holder is gone (a restart). The cut-off run does
+   * not count as an attempt. Returns the released envelopes.
+   */
+  function releaseLeases(as, { now = Date.now() } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    return withTx(db, () => {
+      const rows = db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+        WHERE d.recipient = ? AND d.state = 'leased' AND m.expires_at > ? ORDER BY d.queued_at ASC`).all(as, now);
+      db.prepare(`UPDATE deliveries SET state = 'queued', lease_token = NULL, lease_until = NULL, attempts = MAX(attempts - 1, 0)
+        WHERE recipient = ? AND state = 'leased'`).run(as);
+      return rows.map((r) => envRow({ ...r, recipients: jsonCol([as]) }));
+    }, 'releaseLeases');
+  }
+
+  /** What waits for `as`: all pending (`depth`), not yet taken (`waiting`), and when the oldest was sent. Read-only. */
+  function queueStats(as, now = Date.now()) {
+    if (!ADDRESS.test(as)) return { depth: 0, waiting: 0, oldestAt: null };
+    const row = db.prepare(`SELECT COUNT(*) AS depth, SUM(d.state = 'queued' OR d.lease_until < ?) AS waiting, MIN(m.created_at) AS oldest
+      FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state IN ('queued','leased') AND m.expires_at > ?`).get(now, as, now);
+    return { depth: Number(row.depth) || 0, waiting: Number(row.waiting) || 0, oldestAt: row.oldest == null ? null : Number(row.oldest) };
+  }
+
+  function renewClaim(as, id, token, { leaseMs = LEASE_MS, now = Date.now() } = {}) {
+    if (!ADDRESS.test(as) || !MESSAGE_ID.test(String(id || '')) || !token) return false;
+    const r = db.prepare(`UPDATE deliveries SET lease_until = ?
+      WHERE message_id = ? AND recipient = ? AND lease_token = ? AND state = 'leased'`).run(now + Math.max(1, leaseMs), id, as, token);
+    return !!(r && r.changes);
+  }
+
+  function markDelivered(as, ids, { via = 'hook', awaitingReply = false, now = Date.now() } = {}) {
+    const list = (Array.isArray(ids) ? ids : [ids]).filter((id) => MESSAGE_ID.test(id));
+    if (!ADDRESS.test(as) || !list.length) return 0;
+    return withTx(db, () => {
+      let n = 0;
+      for (const id of list) {
+        const r = db.prepare(`UPDATE deliveries SET state = 'delivered', delivered_at = ?, delivered_via = ?,
+          awaiting_reply = ?, lease_token = NULL, lease_until = NULL
+          WHERE message_id = ? AND recipient = ? AND state IN ('queued','leased','delivered')`).run(
+          now, via, awaitingReply ? 1 : 0, id, as);
+        if (r && r.changes) n++;
+      }
+      return n;
+    }, 'markDelivered');
+  }
+
+  /** Your messages shown mid-turn as a side chat that the agent has not answered yet. */
+  function sideUnanswered(as) {
+    if (!ADDRESS.test(as)) return [];
+    return db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state = 'delivered' AND d.delivered_via = 'side' AND m.sender = 'user' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC`).all(as, Date.now()).map((r) => ({
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+      text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+      reaction: r.reaction, meta: parseJson(r.meta, {}),
+    }));
+  }
+
+  function awaiting(as) {
+    if (!ADDRESS.test(as)) return [];
+    return db.prepare(`SELECT d.message_id AS id, m.sender AS sender FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.awaiting_reply = 1 AND d.state = 'delivered' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC`).all(as, Date.now());
+  }
+
+  /**
+   * A reply was expected for these, but the turn that should have answered them is over. They stop waiting, so a later,
+   * unrelated answer is never captured, and are not offered again (they stay delivered, unanswered).
+   */
+  function releaseAwaiting(as) {
+    if (!ADDRESS.test(as)) return 0;
+    const r = db.prepare(`UPDATE deliveries SET awaiting_reply = 0, delivered_via = 'retried'
+      WHERE recipient = ? AND awaiting_reply = 1 AND state = 'delivered'`).run(as);
+    return Number(r && r.changes) || 0;
+  }
+
+  function ack(as, id, { reply = null, fromName = null, reaction = null } = {}, directory) {
+    if (!ADDRESS.test(as) || !MESSAGE_ID.test(String(id || ''))) return { error: 'bad ack' };
+    return withTx(db, () => {
+      const del = getDel.get(id, as);
+      if (!del) return { error: 'no such message for you' };
+      const orig = getMsg.get(id);
+      if (!orig) return { error: 'no such message for you' };
+      if (del.state !== 'acked') {
+        db.prepare(`UPDATE deliveries SET state = 'acked', acked_at = ?, awaiting_reply = 0, lease_token = NULL, lease_until = NULL
+          WHERE message_id = ? AND recipient = ?`).run(Date.now(), id, as);
+      }
+      let answer = null;
+      const wantReply = (typeof reply === 'string' && reply.trim()) || reaction;
+      if (wantReply && del.state !== 'acked') {
+        const topic = orig.sender === 'user' ? 'user' : orig.sender === 'manager' ? 'manager' : `agent/${orig.sender}`;
+        const inner = publish({
+          id: edgeId('r', id, as), from: as, fromName, topic, type: 'REPLY',
+          body: typeof reply === 'string' && reply.trim() ? reply : 'Reacted',
+          reaction, replyTo: id,
+        }, directory);
+        answer = inner;
+      } else if (wantReply && del.state === 'acked') {
+        const existing = byReply.get(id);
+        if (existing) answer = { id: existing.id };
+        else {
+          const topic = orig.sender === 'user' ? 'user' : orig.sender === 'manager' ? 'manager' : `agent/${orig.sender}`;
+          answer = publish({
+            id: edgeId('r', id, as), from: as, fromName, topic, type: 'REPLY',
+            body: typeof reply === 'string' && reply.trim() ? reply : 'Reacted',
+            reaction, replyTo: id,
+          }, directory);
+        }
+      }
+      return { ok: true, reply: answer && !answer.error ? answer.id : null };
+    }, 'ack');
+  }
+
+  function replyTo(id) {
+    const r = byReply.get(id);
+    if (!r) return null;
+    const status = statusOf(r.id);
+    return envRow({ ...r, recipients: jsonCol(status.map((s) => s.to)) }, status);
+  }
+
+  function statusOf(idOrEnv, now = Date.now()) {
+    const id = typeof idOrEnv === 'string' ? idOrEnv : idOrEnv && idOrEnv.id;
+    const orig = getMsg.get(id);
+    if (!orig) return [];
+    return delsOf.all(id).map((d) => {
+      let state = d.state;
+      if (state === 'queued' && now > orig.expires_at) state = 'expired';
+      if (state === 'delivered' && orig.needs_reply && now > orig.expires_at) state = 'unacked';
+      if (state === 'leased' && d.lease_until && d.lease_until < now) state = 'queued';
+      return { to: d.recipient, state, deliveredAt: d.delivered_at, via: d.delivered_via, ackedAt: d.acked_at, attempts: d.attempts };
+    });
+  }
+
+  const withStatus = (rows, now = Date.now()) => rows.map((m) => {
+    const status = statusOf(m.id, now);
+    return envRow({ ...m, recipients: jsonCol(status.map((s) => s.to)) }, status);
+  });
+
+  /** The newest `limit` messages since `since`, oldest first. */
+  function messages({ since = 0, limit = 200 } = {}) {
+    const n = Math.max(1, Math.min(Number(limit) || 200, 5000));
+    return withStatus(db.prepare('SELECT * FROM messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT ?').all(since, n).reverse());
+  }
+
+  /** Messages sent by or delivered to one address, newest 5000, oldest first. */
+  function involving(address, since = 0) {
+    return withStatus(db.prepare(`SELECT * FROM messages WHERE created_at >= ? AND (sender = ? OR id IN (SELECT message_id FROM deliveries WHERE recipient = ?))
+      ORDER BY created_at DESC LIMIT 5000`).all(since, address, address).reverse());
+  }
+
+  function pendingCount(as) {
+    if (!ADDRESS.test(as)) return 0;
+    expire();
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state IN ('queued','leased') AND m.expires_at > ?`).get(as, Date.now());
+    return Number(row && row.n) || 0;
+  }
+
+  /** Compatibility: claim then mark delivered (listen/CLI). */
+  function take(as, via = 'listen') {
+    const got = claim(as, { via, limit: 50 });
+    if (got.length) markDelivered(as, got.map((m) => m.id), { via, awaitingReply: false });
+    return got;
+  }
+
+  return { publish, claim, peek, releaseLeases, queueStats, renewClaim, markDelivered, sideUnanswered, awaiting, releaseAwaiting, ack, replyTo, statusOf, messages, involving, pendingCount, take, expire };
+}

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