@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/lib/reconcileView.js

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The import reconciliation view (cloud-first ADR-4): one machine's imported items as families of identities, each a
+ * count and a hash, so the connector's fresh scan and the Pulse log can be compared item for item. The connector keeps
+ * a byte-identical copy (agentpulse-cli-plugin-pulse src/lib/reconcileView.js, checked by its tests) and builds its
+ * side with it.
+ */
+export const RECONCILE_TYPES = Object.freeze([
+  'channel.created', 'post.created', 'message.published', 'message.retracted', 'actor.registered', 'actor.row_updated',
+  'persona.updated', 'delivery.updated', 'stream.updated', 'request.created', 'delivery.accepted', 'settings.changed',
+  'audit.recorded', 'status.overridden', 'fact.removed',
+]);
+
+const FACT_KIND = Object.freeze({
+  'delivery.updated': 'delivery', 'stream.updated': 'stream', 'request.created': 'request', 'delivery.accepted': 'accepted',
+  'settings.changed': 'settings', 'audit.recorded': 'event',
+});
+
+/** A count and a hash over the keys, in the order given (posts) or sorted (every other family). */
+export function digest(keys) {
+  return { count: keys.length, sha: createHash('sha256').update(keys.join('\n'), 'utf8').digest('hex').slice(0, 16) };
+}
+
+const sorted = (set) => [...set].sort();
+
+/**
+ * Entries `{ type, key, channel, id, topic, factKey, kind, actorId, digest }` in log order (the connector's in send
+ * order). A post or message hashes as `<key> <sha256 of its body>`, so a changed body is a mismatch too. Returns the
+ * serializable view and the identity sets behind it.
+ */
+export function reconcileFamilies(entries) {
+  const channels = new Set();
+  const posts = new Map();
+  const messages = new Map();
+  const retracted = new Set();
+  const actors = new Set();
+  const agentRows = new Set();
+  const personas = new Set();
+  const statusOverrides = new Set();
+  const facts = new Map(Object.values(FACT_KIND).map((kind) => [kind, new Set()]));
+  const removed = [];
+  for (const entry of entries) {
+    switch (entry.type) {
+      case 'channel.created':
+        channels.add(entry.factKey);
+        break;
+      case 'post.created':
+        channels.add(entry.channel);
+        if (!posts.has(entry.channel)) posts.set(entry.channel, []);
+        posts.get(entry.channel).push({ key: entry.key, digest: entry.digest });
+        break;
+      case 'message.published':
+        messages.set(entry.id, { topic: entry.topic, digest: entry.digest });
+        break;
+      case 'message.retracted':
+        retracted.add(entry.id);
+        break;
+      case 'actor.registered':
+        actors.add(entry.id);
+        break;
+      case 'actor.row_updated':
+        agentRows.add(entry.id);
+        break;
+      case 'persona.updated':
+        personas.add(entry.actorId);
+        break;
+      case 'delivery.updated':
+      case 'request.created':
+      case 'delivery.accepted':
+        facts.get(FACT_KIND[entry.type]).add(entry.id);
+        break;
+      case 'stream.updated':
+      case 'settings.changed':
+        facts.get(FACT_KIND[entry.type]).add(entry.factKey);
+        break;
+      case 'audit.recorded':
+        facts.get('event').add(entry.key);
+        break;
+      case 'status.overridden':
+        statusOverrides.add(entry.factKey);
+        break;
+      case 'fact.removed':
+        removed.push(entry);
+        break;
+      default:
+        throw new Error(`reconcile: unhandled type ${entry.type}`);
+    }
+  }
+  for (const id of retracted) messages.delete(id);
+  for (const entry of removed) {
+    if (entry.kind === 'agent-row') agentRows.delete(entry.factKey);
+    else if (entry.kind === 'status_override') statusOverrides.delete(entry.factKey);
+    else facts.get(entry.kind)?.delete(entry.factKey);
+  }
+  const byTopic = new Map();
+  for (const [id, { topic, digest: body }] of messages) {
+    if (!byTopic.has(topic)) byTopic.set(topic, []);
+    byTopic.get(topic).push(`${id} ${body}`);
+  }
+  const line = (post) => `${post.key} ${post.digest}`;
+  const allPosts = [...posts.values()].flat().map(line);
+  return {
+    sets: { channels, posts, messages, actors, agentRows, personas, statusOverrides, facts },
+    view: {
+      channels: digest(sorted(channels)),
+      posts: { ...digest(allPosts), byChannel: Object.fromEntries([...posts].sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, list]) => [key, digest(list.map(line))])) },
+      messages: { ...digest([...messages].map(([id, { digest: body }]) => `${id} ${body}`).sort()), byTopic: Object.fromEntries([...byTopic].sort(([a], [b]) => (a < b ? -1 : 1)).map(([topic, ids]) => [topic, digest(ids.sort())])) },
+      actors: digest(sorted(actors)),
+      agentRows: digest(sorted(agentRows)),
+      personas: digest(sorted(personas)),
+      statusOverrides: digest(sorted(statusOverrides)),
+      facts: Object.fromEntries([...facts].map(([kind, keys]) => [kind, digest(sorted(keys))])),
+    },
+  };
+}
+
+/** A log row (or a connector command) as a reconcile entry; `digest` is the sha256 hex of a post or message body. */
+export function reconcileEntry(type, key, payload = {}, digest = null) {
+  return {
+    type, key, channel: payload.channel ?? null, id: payload.id ?? null, topic: payload.topic ?? null,
+    factKey: payload.key ?? null, kind: payload.kind ?? null, actorId: payload.actorId ?? null, digest,
+  };
+}
+
+/** The sha256 hex of a body, as the state tables store it (agent_hub_posts.body_digest). */
+export function bodyDigest(body) {
+  return createHash('sha256').update(String(body ?? ''), 'utf8').digest('hex');
+}

package/src/lib/runnerStore.js

@@ -0,0 +1,418 @@
+import { chmod } from 'node:fs/promises';
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { openDatabase } from './sqlite.js';
+import { ensureOwnerOnlyDirectory } from './storage.js';
+
+export const RUNNER_DB_FILE = 'runner.db';
+/** The meta key of the cutover backup the hub tables were seeded from: `{ file, sha256, at, counts, rolledBackAt? }`. */
+export const SEED_META = 'seeded_from';
+/** The meta key of the repo and worktree roots the upload redactor learned, `{ repo, worktree }`: a union that never shrinks. */
+export const REDACTION_ROOTS_META = 'redaction_roots';
+// §6.2: the pending backlog is capped; acknowledged keys live in `sent` and do not count against it.
+export const OUTBOX_MAX_PENDING = 50_000;
+
+const SCHEMA = [
+  'CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)',
+  'CREATE TABLE IF NOT EXISTS cursor (source TEXT PRIMARY KEY, position TEXT NOT NULL)',
+  `CREATE TABLE IF NOT EXISTS outbox (
+     ord INTEGER PRIMARY KEY AUTOINCREMENT,
+     key TEXT NOT NULL UNIQUE,
+     grp TEXT NOT NULL,
+     type TEXT NOT NULL,
+     payload TEXT NOT NULL,
+     source TEXT NOT NULL,
+     attempts INTEGER NOT NULL DEFAULT 0,
+     next_at INTEGER NOT NULL DEFAULT 0,
+     last_error TEXT,
+     enqueued_at INTEGER NOT NULL)`,
+  'CREATE INDEX IF NOT EXISTS outbox_grp ON outbox (grp, ord)',
+  `CREATE TABLE IF NOT EXISTS sent (
+     key TEXT PRIMARY KEY, source TEXT NOT NULL, type TEXT NOT NULL, seq TEXT, duplicate INTEGER NOT NULL, at INTEGER NOT NULL)`,
+  'CREATE INDEX IF NOT EXISTS sent_at ON sent (at)',
+  `CREATE TABLE IF NOT EXISTS dead (
+     key TEXT PRIMARY KEY, grp TEXT NOT NULL, type TEXT NOT NULL, payload TEXT NOT NULL, source TEXT NOT NULL,
+     code TEXT NOT NULL, message TEXT, at INTEGER NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS version (
+     entity TEXT PRIMARY KEY, sha TEXT NOT NULL, raw_sha TEXT, static_sha TEXT, key TEXT NOT NULL, at INTEGER NOT NULL)`,
+  'CREATE TABLE IF NOT EXISTS version_seen (entity TEXT NOT NULL, sha TEXT NOT NULL, count INTEGER NOT NULL, PRIMARY KEY (entity, sha))',
+  `CREATE TABLE IF NOT EXISTS receipt_state (
+     message_id TEXT NOT NULL, recipient TEXT NOT NULL, state TEXT NOT NULL, PRIMARY KEY (message_id, recipient))`,
+  'CREATE TABLE IF NOT EXISTS recent_message (id TEXT PRIMARY KEY, created_at INTEGER NOT NULL, grp TEXT NOT NULL)',
+  `CREATE TABLE IF NOT EXISTS ingested (
+     channel TEXT NOT NULL, ordinal INTEGER NOT NULL, sha TEXT NOT NULL, post_key TEXT NOT NULL, at INTEGER NOT NULL,
+     PRIMARY KEY (channel, ordinal))`,
+  'CREATE TABLE IF NOT EXISTS presence_sent (actor_id TEXT PRIMARY KEY, last_seen INTEGER NOT NULL, sent_at INTEGER NOT NULL)',
+];
+
+const TERMINAL_RECEIPT = new Set(['acked', 'expired']);
+
+/**
+ * The runner's local store (design §6.2), `runner.db` in the connector's config directory: per-source scan cursors,
+ * the durable outbox of commands waiting for the cloud, the keys the cloud acknowledged, dead letters, and what the
+ * scanners last saw of each mutable entity. node:sqlite with WAL and synchronous=FULL; owner-only.
+ */
+export class RunnerStore {
+  static async open(directory, { now = Date.now, maxPending = OUTBOX_MAX_PENDING } = {}) {
+    await ensureOwnerOnlyDirectory(directory);
+    const file = path.join(directory, RUNNER_DB_FILE);
+    const db = openDatabase(file);
+    const run = (sql) => db.prepare(sql).run();
+    run('PRAGMA journal_mode = WAL');
+    run('PRAGMA synchronous = FULL');
+    run('PRAGMA busy_timeout = 5000');
+    for (const statement of SCHEMA) run(statement);
+    await chmod(file, 0o600);
+    return new RunnerStore({ db, file, now, maxPending });
+  }
+
+  /** The store as the daemon left it, for status reads; null when there is none. Writes through it fail. */
+  static openReadOnly(directory, { now = Date.now } = {}) {
+    const file = path.join(directory, RUNNER_DB_FILE);
+    let db;
+    try {
+      db = openDatabase(file, { readOnly: true });
+    } catch {
+      return null;
+    }
+    db.prepare('PRAGMA busy_timeout = 5000').run();
+    return new RunnerStore({ db, file, now, maxPending: OUTBOX_MAX_PENDING });
+  }
+
+  /** A consistent copy of the store in `target` (a file that must not exist), taken without blocking its writer. */
+  static copy(directory, target) {
+    const source = RunnerStore.openReadOnly(directory);
+    if (!source) return false;
+    try {
+      source.db.prepare('VACUUM INTO ?').run(target);
+      return true;
+    } finally {
+      source.close();
+    }
+  }
+
+  constructor({ db, file, now, maxPending }) {
+    this.db = db;
+    this.file = file;
+    this.now = now;
+    this.maxPending = maxPending;
+    this.depth = 0;
+  }
+
+  close() {
+    this.db.close();
+  }
+
+  /**
+   * Run `fn` in one immediate transaction: everything it enqueues and every cursor it moves commit together. Inside a
+   * transaction already open on this connection (the runner's capture) it joins that one.
+   */
+  transaction(fn) {
+    if (this.depth > 0 || this.db.isTransaction) return fn();
+    this.db.prepare('BEGIN IMMEDIATE').run();
+    this.depth += 1;
+    try {
+      const out = fn();
+      this.db.prepare('COMMIT').run();
+      return out;
+    } catch (error) {
+      this.db.prepare('ROLLBACK').run();
+      throw error;
+    } finally {
+      this.depth -= 1;
+    }
+  }
+
+  meta(key) {
+    const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+    return row ? JSON.parse(row.value) : null;
+  }
+
+  setMeta(key, value) {
+    this.db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value')
+      .run(key, JSON.stringify(value));
+  }
+
+  cursor(source) {
+    const row = this.db.prepare('SELECT position FROM cursor WHERE source = ?').get(source);
+    return row ? JSON.parse(row.position) : null;
+  }
+
+  setCursor(source, position) {
+    this.db.prepare('INSERT INTO cursor (source, position) VALUES (?, ?) ON CONFLICT (source) DO UPDATE SET position = excluded.position')
+      .run(source, JSON.stringify(position));
+  }
+
+  /** Whether a key was ever enqueued: pending, acknowledged or dead. */
+  known(key) {
+    return Boolean(this.db.prepare(
+      'SELECT 1 AS found FROM outbox WHERE key = ? UNION ALL SELECT 1 FROM sent WHERE key = ? UNION ALL SELECT 1 FROM dead WHERE key = ? LIMIT 1',
+    ).get(key, key, key));
+  }
+
+  pendingCount() {
+    return Number(this.db.prepare('SELECT COUNT(*) AS n FROM outbox').get().n);
+  }
+
+  /**
+   * Queue commands (`{ key, group, type, payload, source }`), skipping any key already known. Returns how many were new.
+   * Past the pending cap it refuses the whole call with pulse_backlog, so the caller's cursor does not move either.
+   */
+  enqueue(entries) {
+    return this.transaction(() => {
+      const insert = this.db.prepare(
+        `INSERT INTO outbox (key, grp, type, payload, source, enqueued_at)
+         SELECT ?, ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM sent WHERE key = ?) AND NOT EXISTS (SELECT 1 FROM dead WHERE key = ?)
+         ON CONFLICT (key) DO NOTHING`,
+      );
+      let added = 0;
+      for (const entry of entries) {
+        added += Number(insert.run(entry.key, entry.group, entry.type, JSON.stringify(entry.payload), entry.source, this.now(), entry.key, entry.key).changes);
+      }
+      if (added && this.pendingCount() > this.maxPending) {
+        throw new HubError('pulse_backlog', `More than ${this.maxPending} commands are waiting for Pulse`);
+      }
+      return added;
+    });
+  }
+
+  /**
+   * The next batch to send: the oldest due rows in enqueue order, at most `max` rows and `maxBytes` of payload. A row
+   * behind an earlier row of its own group that is not due (backing off) waits for it, so each group keeps its order;
+   * other groups go on.
+   */
+  nextBatch({ max = 100, maxBytes = 480 * 1024 } = {}) {
+    const now = this.now();
+    const blocked = new Set();
+    const batch = [];
+    const corrupt = [];
+    let bytes = 0;
+    for (const row of this.db.prepare('SELECT ord, key, grp, type, payload, source, attempts, next_at FROM outbox ORDER BY ord').iterate()) {
+      if (blocked.has(row.grp)) continue;
+      if (Number(row.next_at) > now) {
+        blocked.add(row.grp);
+        continue;
+      }
+      const size = Buffer.byteLength(row.payload, 'utf8') + row.key.length + row.type.length + 64;
+      if (batch.length && bytes + size > maxBytes) break;
+      let payload;
+      try {
+        payload = JSON.parse(row.payload);
+      } catch {
+        corrupt.push(row.key);
+        blocked.add(row.grp);
+        continue;
+      }
+      batch.push({ key: row.key, group: row.grp, type: row.type, payload, source: row.source, attempts: Number(row.attempts) });
+      bytes += size;
+      if (batch.length >= max) break;
+    }
+    for (const key of corrupt) this.dead(key, { code: 'corrupt_row', message: 'The stored payload could not be read' });
+    return batch;
+  }
+
+  /** The cloud stored (or already had) this key. */
+  acked(key, { seq = null, duplicate = false } = {}) {
+    this.transaction(() => {
+      const row = this.db.prepare('SELECT source, type FROM outbox WHERE key = ?').get(key);
+      if (!row) return;
+      this.db.prepare('INSERT INTO sent (key, source, type, seq, duplicate, at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (key) DO NOTHING')
+        .run(key, row.source, row.type, seq === null ? null : String(seq), duplicate ? 1 : 0, this.now());
+      this.db.prepare('DELETE FROM outbox WHERE key = ?').run(key);
+    });
+  }
+
+  /** A retryable refusal: the row stays first in its group and is due again after `delayMs`. */
+  retry(key, { code, delayMs }) {
+    this.db.prepare('UPDATE outbox SET attempts = attempts + 1, next_at = ?, last_error = ? WHERE key = ?').run(this.now() + delayMs, code, key);
+  }
+
+  /** Held behind an earlier command of its group: due again after `delayMs`, without counting an attempt. */
+  hold(key, { code, delayMs }) {
+    this.db.prepare('UPDATE outbox SET next_at = ?, last_error = ? WHERE key = ?').run(this.now() + delayMs, code, key);
+  }
+
+  /** A refusal that repeating cannot fix: the row leaves the outbox with its reason. */
+  dead(key, { code, message = null }) {
+    this.transaction(() => {
+      const row = this.db.prepare('SELECT grp, type, payload, source FROM outbox WHERE key = ?').get(key);
+      if (!row) return;
+      this.db.prepare(
+        `INSERT INTO dead (key, grp, type, payload, source, code, message, at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (key) DO UPDATE SET code = excluded.code, message = excluded.message, at = excluded.at`,
+      ).run(key, row.grp, row.type, row.payload, row.source, code, message, this.now());
+      this.db.prepare('DELETE FROM outbox WHERE key = ?').run(key);
+    });
+  }
+
+  /** A command refused before it was queued (it never reaches the cloud), recorded with its reason. */
+  refuse(entry, { code, message = null }) {
+    this.db.prepare(
+      `INSERT INTO dead (key, grp, type, payload, source, code, message, at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT (key) DO NOTHING`,
+    ).run(entry.key, entry.group, entry.type, JSON.stringify(entry.payload ?? null), entry.source, code, message, this.now());
+  }
+
+  /** The code a key was refused or dead-lettered with, or null. */
+  deadCode(key) {
+    return this.db.prepare('SELECT code FROM dead WHERE key = ?').get(key)?.code ?? null;
+  }
+
+  /** Every queued command in queue order, payload parsed (a reconcile reads a scratch store's whole scan this way). */
+  planned() {
+    return this.db.prepare('SELECT key, grp, type, payload, source FROM outbox ORDER BY ord').all()
+      .map((row) => ({ key: row.key, group: row.grp, type: row.type, payload: JSON.parse(row.payload), source: row.source }));
+  }
+
+  /** Every set-aside key with its code (all of them; deadRows is the newest few). */
+  deadKeys() {
+    return this.db.prepare('SELECT key, type, source, code FROM dead ORDER BY key').all().map((row) => ({ ...row }));
+  }
+
+  deadRows({ limit = 20 } = {}) {
+    return this.db.prepare('SELECT key, type, source, code, message, at FROM dead ORDER BY at DESC LIMIT ?').all(limit).map((row) => ({ ...row }));
+  }
+
+  /** Counts per source: pending, sent (written or duplicate) and dead (by code). */
+  counts() {
+    const out = {};
+    const at = (source) => (out[source] ||= { pending: 0, written: 0, duplicate: 0, dead: {} });
+    for (const row of this.db.prepare('SELECT source, COUNT(*) AS n FROM outbox GROUP BY source').all()) at(row.source).pending = Number(row.n);
+    for (const row of this.db.prepare('SELECT source, duplicate, COUNT(*) AS n FROM sent GROUP BY source, duplicate').all()) {
+      at(row.source)[row.duplicate ? 'duplicate' : 'written'] = Number(row.n);
+    }
+    for (const row of this.db.prepare('SELECT source, code, COUNT(*) AS n FROM dead GROUP BY source, code').all()) at(row.source).dead[row.code] = Number(row.n);
+    return out;
+  }
+
+  version(entity) {
+    const row = this.db.prepare('SELECT sha, raw_sha, static_sha, key, at FROM version WHERE entity = ?').get(entity);
+    return row ? { sha: row.sha, rawSha: row.raw_sha, staticSha: row.static_sha, key: row.key, at: Number(row.at) } : null;
+  }
+
+  /**
+   * The key for this content of an entity: `<prefix><sep><sha>` the first time this content is sent, and
+   * `<prefix><sep><sha>.<k>` when it returns after another version (A→B→A), so the return is a new event that applies.
+   */
+  versionKey(entity, prefix, sha, separator = ':') {
+    const seen = this.db.prepare('SELECT count FROM version_seen WHERE entity = ? AND sha = ?').get(entity, sha);
+    const count = seen ? Number(seen.count) : 0;
+    return count === 0 ? `${prefix}${separator}${sha}` : `${prefix}${separator}${sha}.${count}`;
+  }
+
+  /** Record that this content of an entity was queued under `key`. */
+  setVersion(entity, { sha, rawSha = null, staticSha = null, key }) {
+    const last = this.version(entity);
+    if (last?.sha !== sha) {
+      this.db.prepare(
+        `INSERT INTO version_seen (entity, sha, count) VALUES (?, ?, 1)
+         ON CONFLICT (entity, sha) DO UPDATE SET count = count + 1`,
+      ).run(entity, sha);
+    }
+    this.db.prepare(
+      `INSERT INTO version (entity, sha, raw_sha, static_sha, key, at) VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT (entity) DO UPDATE SET sha = excluded.sha, raw_sha = excluded.raw_sha, static_sha = excluded.static_sha,
+         key = excluded.key, at = excluded.at`,
+    ).run(entity, sha, rawSha, staticSha, key, this.now());
+  }
+
+  /** The raw form last read, without changing what was sent (an unchanged row skips redaction next time). */
+  touchVersion(entity, rawSha) {
+    this.db.prepare('UPDATE version SET raw_sha = ? WHERE entity = ?').run(rawSha, entity);
+  }
+
+  dropVersion(entity) {
+    this.db.prepare('DELETE FROM version WHERE entity = ?').run(entity);
+  }
+
+  entities(prefix) {
+    return this.db.prepare("SELECT entity FROM version WHERE entity >= ? AND entity < ? || char(1114111)").all(prefix, prefix).map((row) => row.entity);
+  }
+
+  /** The receipt state last queued for each recipient row still able to change (not acked or expired). */
+  openReceipts() {
+    return this.db.prepare("SELECT message_id, recipient, state FROM receipt_state WHERE state NOT IN ('acked', 'expired')").all()
+      .map((row) => ({ messageId: row.message_id, recipient: row.recipient, state: row.state }));
+  }
+
+  receiptState(messageId, recipient) {
+    return this.db.prepare('SELECT state FROM receipt_state WHERE message_id = ? AND recipient = ?').get(messageId, recipient)?.state ?? null;
+  }
+
+  setReceiptState(messageId, recipient, state) {
+    this.db.prepare(
+      `INSERT INTO receipt_state (message_id, recipient, state) VALUES (?, ?, ?)
+       ON CONFLICT (message_id, recipient) DO UPDATE SET state = excluded.state`,
+    ).run(messageId, recipient, state);
+  }
+
+  dropReceipts(messageId) {
+    this.db.prepare('DELETE FROM receipt_state WHERE message_id = ?').run(messageId);
+  }
+
+  rememberMessage(id, createdAt, group) {
+    this.db.prepare('INSERT INTO recent_message (id, created_at, grp) VALUES (?, ?, ?) ON CONFLICT (id) DO NOTHING').run(id, createdAt, group);
+  }
+
+  recentMessages(sinceMs) {
+    return this.db.prepare('SELECT id, created_at, grp FROM recent_message WHERE created_at >= ? ORDER BY created_at').all(sinceMs)
+      .map((row) => ({ id: row.id, createdAt: Number(row.created_at), group: row.grp }));
+  }
+
+  forgetMessage(id) {
+    this.db.prepare('DELETE FROM recent_message WHERE id = ?').run(id);
+  }
+
+  pruneRecentMessages(beforeMs) {
+    this.db.prepare('DELETE FROM recent_message WHERE created_at < ?').run(beforeMs);
+  }
+
+  ingested(channel) {
+    return this.db.prepare('SELECT ordinal, sha, post_key, at FROM ingested WHERE channel = ? ORDER BY ordinal').all(channel)
+      .map((row) => ({ ordinal: Number(row.ordinal), sha: row.sha, postKey: row.post_key, at: Number(row.at) }));
+  }
+
+  /** The key a channel's block (its digest and occurrence) was first sent under, or null. */
+  ingestedKey(channel, sha) {
+    return this.db.prepare('SELECT post_key FROM ingested WHERE channel = ? AND sha = ?').get(channel, sha)?.post_key ?? null;
+  }
+
+  setIngested(channel, { ordinal, sha, postKey, at }) {
+    this.db.prepare(
+      `INSERT INTO ingested (channel, ordinal, sha, post_key, at) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT (channel, ordinal) DO UPDATE SET sha = excluded.sha, post_key = excluded.post_key, at = excluded.at`,
+    ).run(channel, ordinal, sha, postKey, at);
+  }
+
+  /** What one channel file holds now, by position, replacing what was recorded before. */
+  replaceIngested(channel, rows) {
+    this.transaction(() => {
+      this.db.prepare('DELETE FROM ingested WHERE channel = ?').run(channel);
+      for (const row of rows) this.setIngested(channel, row);
+    });
+  }
+
+  presenceSent(actorId) {
+    const row = this.db.prepare('SELECT last_seen, sent_at FROM presence_sent WHERE actor_id = ?').get(actorId);
+    return row ? { lastSeen: Number(row.last_seen), sentAt: Number(row.sent_at) } : null;
+  }
+
+  setPresenceSent(actorId, lastSeen) {
+    this.db.prepare(
+      `INSERT INTO presence_sent (actor_id, last_seen, sent_at) VALUES (?, ?, ?)
+       ON CONFLICT (actor_id) DO UPDATE SET last_seen = excluded.last_seen, sent_at = excluded.sent_at`,
+    ).run(actorId, lastSeen, this.now());
+  }
+
+  /** Whether the cloud acknowledged `key` as a command of `type`. */
+  sentAs(key, type) {
+    return Boolean(this.db.prepare('SELECT 1 AS found FROM sent WHERE key = ? AND type = ?').get(key, type));
+  }
+
+  /** Acknowledged keys older than `beforeMs` go; the cloud's dedupe is the backstop for anything resent after that. */
+  pruneSent(beforeMs) {
+    return Number(this.db.prepare('DELETE FROM sent WHERE at < ?').run(beforeMs).changes);
+  }
+}
+
+export { TERMINAL_RECEIPT };

package/src/lib/serviceManager.js

@@ -127,6 +127,7 @@ export class ServiceManager {
     ),
     execute = execFile,
     wait = delay,
+    launchAgentsDir = path.join(home, 'Library', 'LaunchAgents'),
   }) {
     this.platform = platform;
     this.home = home;
@@ -137,6 +138,7 @@ export class ServiceManager {
     this.logDir = logDir;
     this.execute = execute;
     this.wait = wait;
+    this.launchAgentsDir = launchAgentsDir;
   }
 
   serviceFile() {
@@ -342,6 +344,65 @@ export class ServiceManager {
     return { state: 'stopped', pid: null, serviceFile: this.serviceFile() };
   }
 
+  /**
+   * Another LaunchAgent of this machine, by label (the old local hub, its keep-awake helper), for cutover and
+   * rollback. macOS only; every call goes through the injected executor.
+   */
+  #requireLaunchd(label) {
+    if (this.platform !== 'darwin') throw new HubError('HUB_UNSUPPORTED_PLATFORM', `${label} is a macOS LaunchAgent`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(label)) throw new HubError('HUB_SERVICE_LABEL_INVALID', `Bad LaunchAgent label: ${label}`);
+    return `gui/${this.uid}/${label}`;
+  }
+
+  plistFor(label) {
+    this.#requireLaunchd(label);
+    return path.join(this.launchAgentsDir, `${label}.plist`);
+  }
+
+  /** `{ loaded, pid, plist }` for a LaunchAgent label. */
+  async labelState(label) {
+    const target = this.#requireLaunchd(label);
+    const plist = this.plistFor(label);
+    try {
+      const result = await this.execute('/bin/launchctl', ['print', target]);
+      return { loaded: true, pid: Number(result.stdout.match(/\bpid\s*=\s*(\d+)/)?.[1]) || null, plist, installed: await exists(plist) };
+    } catch {
+      return { loaded: false, pid: null, plist, installed: await exists(plist) };
+    }
+  }
+
+  /** Unload a LaunchAgent and keep it from loading again at login (`disable`), until `restoreLabel`. */
+  async retireLabel(label) {
+    const target = this.#requireLaunchd(label);
+    try {
+      await this.execute('/bin/launchctl', ['bootout', target]);
+    } catch (error) {
+      if (!ABSENT_SERVICE.test(`${error.message || ''}\n${error.stderr || ''}`)) {
+        throw new HubError('HUB_SERVICE_STOP_FAILED', `launchd could not unload ${label}`, { cause: error });
+      }
+    }
+    await this.execute('/bin/launchctl', ['disable', target]);
+    return this.labelState(label);
+  }
+
+  /** Undo `retireLabel`: enable the label again and load its plist. */
+  async restoreLabel(label) {
+    const target = this.#requireLaunchd(label);
+    await this.execute('/bin/launchctl', ['enable', target]);
+    let lastError = null;
+    for (let attempt = 0; attempt < START_ATTEMPTS; attempt += 1) {
+      if (attempt > 0) await this.wait(START_RETRY_MS * attempt);
+      if ((await this.labelState(label)).loaded) return this.labelState(label);
+      try {
+        await this.execute('/bin/launchctl', ['bootstrap', `gui/${this.uid}`, this.plistFor(label)]);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if ((await this.labelState(label)).loaded) return this.labelState(label);
+    throw new HubError('HUB_SERVICE_START_FAILED', `launchd could not load ${label}`, { cause: lastError });
+  }
+
   async health({ freshMs = 30_000, after = 0 } = {}) {
     const health = await readOwnerOnlyJson(path.join(this.configDir, 'daemon-health.json'));
     const heartbeat = Date.parse(health?.heartbeatAt);