@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/runner/applier.js

@@ -0,0 +1,297 @@
+import { acceptDelivery } from '../hub/lib/store.mjs';
+import { applyRemotePresence } from './busIdentity.js';
+
+/** How far a recipient row has got; a cloud receipt moves a local row only forward. `leased` stays on the machine. */
+const RANK = { queued: 0, leased: 0, delivered: 1, acked: 2, expired: 3 };
+const RECEIPT_STATE = { 'receipt.delivered': 'delivered', 'receipt.acked': 'acked', 'receipt.expired': 'expired' };
+
+/** Cloud types this machine keeps no local copy of; recorded as seen, never quarantined. */
+const NOT_LOCAL = new Set([
+  'project.created', 'project.updated', 'project.removed', 'project.member_added', 'project.role_changed', 'project.member_removed',
+  'rules.pack_enabled', 'rules.pack_disabled', 'rules.rule_toggled', 'team.flag_set', 'persona.updated', 'channel.created',
+  'post.edited', 'post.removed', 'decision.recorded',
+]);
+
+const json = (value) => (value === undefined || value === null ? null : typeof value === 'string' ? value : JSON.stringify(value));
+
+/** The ordering group a local change to this event's entity is queued under (Phase 2's grp), or null. */
+function entityGroup(event) {
+  const p = event.payload || {};
+  switch (event.type) {
+    case 'actor.registered':
+    case 'actor.updated':
+      return `actor:${p.id}`;
+    case 'actor.row_updated':
+      return `fact:agent-row:${p.id}`;
+    case 'delivery.updated':
+      return `fact:delivery:${p.id}`;
+    case 'stream.updated':
+      return `fact:stream:${p.key}`;
+    case 'request.created':
+      return `fact:request:${p.id}`;
+    case 'delivery.accepted':
+      return `fact:accepted:${p.id}`;
+    case 'status.overridden':
+      return `fact:status_override:${p.key}`;
+    case 'settings.changed':
+      return `fact:settings:${p.key}`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Applies `/connector/sync` pages to runner.db (design §4.5, §6.3): one transaction per page, each event in its own
+ * savepoint, with capture off so nothing applied here is sent back, and the cursor advanced in the same transaction.
+ *
+ * - An event is skipped as this machine's own when its key is already known (sent, pending or dead here), or when it
+ *   came from this machine at or below the cutover seq, whose content the seed already holds (N3).
+ * - A change to an entity whose own newer version is still in the outbox is deferred until that version is acked,
+ *   then applied only if it is later (M1).
+ * - An event that cannot be applied goes to pulse_quarantine with its reason; the cursor still moves past it (I1).
+ */
+export function createApplier({ runner, machineId, cutoverSeq = () => 0, now = Date.now, log = () => {}, checkpoint = () => {} }) {
+  /**
+   * Every machine id this hub's content was sent up under: today's, and those the import and the shadow ran as before a
+   * re-pair (`origin_machines`, recorded at cutover). Up to the cutover seq, their events are already in the seed.
+   */
+  const ownMachines = () => new Set([machineId, ...(runner.store.meta('origin_machines') || [])].filter(Boolean));
+  const { hub, store, capture, mapping } = runner;
+  const { db } = hub;
+  const q = {
+    seen: db.prepare('SELECT 1 AS found FROM pulse_events WHERE seq = ? OR id = ?'),
+    record: db.prepare('INSERT OR IGNORE INTO pulse_events (seq, id, type, key, origin, outcome, applied_at) VALUES (?, ?, ?, ?, ?, ?, ?)'),
+    quarantine: db.prepare('INSERT OR IGNORE INTO pulse_quarantine (seq, id, type, reason, payload, at) VALUES (?, ?, ?, ?, ?, ?)'),
+    defer: db.prepare('INSERT OR IGNORE INTO pulse_deferred (seq, grp, event, at) VALUES (?, ?, ?, ?)'),
+    deferred: db.prepare('SELECT seq, grp, event FROM pulse_deferred ORDER BY seq'),
+    undefer: db.prepare('DELETE FROM pulse_deferred WHERE seq = ?'),
+    pending: db.prepare('SELECT 1 AS found FROM outbox WHERE grp = ? LIMIT 1'),
+    ackedSeq: db.prepare("SELECT MAX(CAST(s.seq AS INTEGER)) AS seq FROM sent s JOIN version v ON v.key = s.key WHERE v.entity = ?"),
+    sent: db.prepare("INSERT INTO sent (key, source, type, seq, duplicate, at) VALUES (?, 'sync', ?, ?, 0, ?) ON CONFLICT (key) DO NOTHING"),
+    cursor: db.prepare('UPDATE pulse_sync SET applied_seq = ?, head = ?, floor = ?, last_ok_at = ?, last_error = NULL WHERE one = 1'),
+    message: 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+    delivery: db.prepare("INSERT OR IGNORE INTO deliveries (message_id, recipient, state, queued_at, attempts) VALUES (?, ?, 'queued', ?, 0)"),
+    receipt: db.prepare('SELECT state FROM deliveries WHERE message_id = ? AND recipient = ?'),
+    messageExists: db.prepare('SELECT 1 AS found FROM messages WHERE id = ?'),
+    fact: 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`),
+    factOf: db.prepare('SELECT payload FROM facts WHERE kind = ? AND key = ?'),
+    dropFact: db.prepare('DELETE FROM facts WHERE kind = ? AND key = ?'),
+    event: db.prepare('INSERT INTO events (at, kind, actor, payload) VALUES (?, ?, ?, ?)'),
+  };
+  const touched = [];
+  const adopt = (change) => touched.push(change);
+
+  function setFact(kind, key, payload, at) {
+    q.fact.run(kind, key, json(payload), Number(at) || now());
+    adopt({ tbl: 'facts', k1: kind, k2: key });
+  }
+
+  function receipt(event) {
+    const p = event.payload;
+    const target = RECEIPT_STATE[event.type];
+    const current = q.receipt.get(p.messageId, p.recipient);
+    if (!current) {
+      if (!q.messageExists.get(p.messageId)) throw Object.assign(new Error(`receipt for a message this machine never had: ${p.messageId}`), { reason: 'message_missing' });
+      q.delivery.run(p.messageId, p.recipient, Number(p.at) || now());
+    } else if (RANK[current.state] >= RANK[target] || current.state === 'expired') {
+      return 'not_forward';
+    }
+    const at = Number(p.at) || now();
+    if (target === 'delivered') {
+      db.prepare(`UPDATE deliveries SET state = 'delivered', delivered_at = COALESCE(delivered_at, ?), delivered_via = COALESCE(?, delivered_via),
+        lease_token = NULL, lease_until = NULL WHERE message_id = ? AND recipient = ?`).run(at, p.via ?? null, p.messageId, p.recipient);
+    } else if (target === 'acked') {
+      db.prepare(`UPDATE deliveries SET state = 'acked', acked_at = ?, delivered_at = COALESCE(delivered_at, ?), awaiting_reply = 0,
+        lease_token = NULL, lease_until = NULL WHERE message_id = ? AND recipient = ?`).run(at, at, p.messageId, p.recipient);
+    } else {
+      db.prepare("UPDATE deliveries SET state = 'expired', lease_token = NULL, lease_until = NULL WHERE message_id = ? AND recipient = ?").run(p.messageId, p.recipient);
+    }
+    adopt({ tbl: 'deliveries', k1: p.messageId, k2: p.recipient });
+    return 'applied';
+  }
+
+  function upsertActor(actor) {
+    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 (@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)
+      ON CONFLICT (id) DO UPDATE SET node_type = excluded.node_type, role = excluded.role, parent_id = excluded.parent_id,
+        delivery_id = excluded.delivery_id, stream_key = excluded.stream_key, cursor_title = excluded.cursor_title,
+        prompt_title = excluded.prompt_title, persona_name = excluded.persona_name, persona_first = excluded.persona_first,
+        persona_username = excluded.persona_username, persona_seed = excluded.persona_seed, persona_json = excluded.persona_json,
+        source = excluded.source, topics = excluded.topics, started_at = excluded.started_at,
+        last_at = MAX(COALESCE(actors.last_at, 0), COALESCE(excluded.last_at, 0)), tokens_est = excluded.tokens_est,
+        msgs_in = excluded.msgs_in, msgs_out = excluded.msgs_out, repo = excluded.repo, channel = excluded.channel,
+        synthetic = excluded.synthetic, extra = excluded.extra`).run({
+      id: actor.id, node_type: actor.node_type, role: actor.role ?? null, parent_id: actor.parent_id ?? null, delivery_id: actor.delivery_id ?? null,
+      stream_key: actor.stream_key ?? null, cursor_title: actor.cursor_title ?? null, prompt_title: actor.prompt_title ?? null,
+      persona_name: actor.persona_name ?? null, persona_first: actor.persona_first ?? null, persona_username: actor.persona_username ?? null,
+      persona_seed: actor.persona_seed ?? null, persona_json: json(actor.persona), source: actor.source || 'registered',
+      topics: json(actor.topics ?? []), started_at: actor.started_at ?? null, last_at: actor.last_at ?? null, tokens_est: actor.tokens_est ?? null,
+      msgs_in: actor.msgs_in ?? 0, msgs_out: actor.msgs_out ?? 0, repo: actor.repo ?? null, channel: actor.channel ?? null,
+      synthetic: actor.synthetic ? 1 : 0, extra: json(actor.extra),
+    });
+    adopt({ tbl: 'actors', k1: actor.id });
+  }
+
+  /** The delivery as the local collector stores it: its streams carried inside it, from their own stream facts. */
+  function deliveryFact(p) {
+    const prior = JSON.parse(q.factOf.get('delivery', p.id)?.payload || 'null');
+    const { streamKeys = [], ...delivery } = p.delivery || {};
+    const byKey = new Map((prior?.streams || []).map((s) => [s.key, s]));
+    const streams = streamKeys.map((key) => {
+      const own = q.factOf.get('stream', key);
+      return own ? { ...JSON.parse(own.payload), key } : byKey.get(key) || { key };
+    });
+    return { ...delivery, streams };
+  }
+
+  function applyOne(event) {
+    const p = event.payload || {};
+    switch (event.type) {
+      case 'message.published': {
+        q.message.run(p.id, p.from, p.topic, p.type, p.body, p.needsAck ? 1 : 0, Number(p.expiresAt), p.replyTo ?? null, p.reaction ?? null,
+          p.fromName ?? null, Number(p.at) || now(), json(p.meta ?? {}));
+        for (const to of p.to || []) q.delivery.run(p.id, to, Number(p.at) || now());
+        return 'applied';
+      }
+      case 'receipt.delivered':
+      case 'receipt.acked':
+      case 'receipt.expired':
+        return receipt(event);
+      case 'message.retracted':
+        db.prepare('DELETE FROM deliveries WHERE message_id = ?').run(p.id);
+        db.prepare('DELETE FROM messages WHERE id = ?').run(p.id);
+        return 'applied';
+      case 'actor.registered':
+      case 'actor.updated':
+        upsertActor({ ...(p.actor || {}), id: p.id });
+        return 'applied';
+      case 'actor.retired':
+        return 'not_local';
+      case 'actor.row_updated':
+        setFact('agent-row', p.id, p.row, p.at);
+        return 'applied';
+      case 'delivery.updated':
+      case 'delivery.created':
+        setFact('delivery', p.id, deliveryFact(p), p.at);
+        return 'applied';
+      case 'stream.updated': {
+        setFact('stream', p.key, p.stream, p.at);
+        const owner = JSON.parse(q.factOf.get('delivery', p.deliveryId)?.payload || 'null');
+        if (owner) setFact('delivery', p.deliveryId, { ...owner, streams: (owner.streams || []).map((s) => (s.key === p.key ? { ...p.stream, key: p.key } : s)) }, p.at);
+        return 'applied';
+      }
+      case 'request.created':
+        setFact('request', p.id, p.request, p.at);
+        return 'applied';
+      case 'delivery.accepted':
+        setFact('accepted', p.id, { at: Number(p.at) || now() }, p.at);
+        acceptDelivery(p.id);
+        return 'applied';
+      case 'settings.changed':
+        setFact('settings', p.key, p.value, p.at);
+        return 'applied';
+      case 'status.overridden':
+        setFact('status_override', p.key, p.override, p.at);
+        return 'applied';
+      case 'fact.removed':
+        q.dropFact.run(p.kind, p.key);
+        return 'applied';
+      case 'audit.recorded':
+        q.event.run(Number(p.at) || now(), p.kind, p.actor ?? null, json(p.data ?? {}));
+        return 'applied';
+      case 'post.created':
+        // Appended to channel.md by the channel bridge after this page commits (render.js), once.
+        return 'applied';
+      default:
+        if (NOT_LOCAL.has(event.type)) return 'not_local';
+        throw Object.assign(new Error(`no local meaning for ${event.type}`), { reason: 'unknown_type' });
+    }
+  }
+
+  const ownEvent = (event, own) => store.known(event.key) || (own.has(event.machineId) && Number(event.seq) <= Number(cutoverSeq()));
+
+  function step(event, { retry = false, own = ownMachines() } = {}) {
+    if (!retry && q.seen.get(event.seq, event.id)) return 'replayed';
+    if (ownEvent(event, own)) return 'own';
+    const group = entityGroup(event);
+    if (group && q.pending.get(group)) {
+      q.defer.run(event.seq, group, JSON.stringify(event), now());
+      return 'deferred';
+    }
+    if (retry && group) {
+      const entity = group;
+      const acked = Number(q.ackedSeq.get(entity)?.seq || 0);
+      if (acked > Number(event.seq)) return 'superseded';
+    }
+    db.prepare('SAVEPOINT pulse_event').run();
+    try {
+      const outcome = applyOne(event);
+      db.prepare('RELEASE pulse_event').run();
+      return outcome;
+    } catch (error) {
+      db.prepare('ROLLBACK TO pulse_event').run();
+      db.prepare('RELEASE pulse_event').run();
+      touched.length = 0;
+      q.quarantine.run(event.seq, event.id ?? null, event.type ?? null, String(error.reason || error.message).slice(0, 300), JSON.stringify(event.payload ?? null).slice(0, 32_000), now());
+      return 'quarantined';
+    }
+  }
+
+  function settle(event, outcome) {
+    q.record.run(event.seq, event.id || `seq:${event.seq}`, event.type || 'unknown', event.key || '', event.machineId ?? null, outcome, now());
+    if (outcome === 'applied' && event.key) q.sent.run(event.key, event.type, String(event.seq), now());
+    for (const change of touched.splice(0)) mapping.adopt?.(change, db);
+  }
+
+  return {
+    /** One page, in one transaction. Returns counts and the cursor it moved to. */
+    apply(page) {
+      const counts = { applied: 0, skipped: 0, deferred: 0, quarantined: 0, notLocal: 0, posts: [] };
+      const own = ownMachines();
+      capture.applying(() => {
+        for (const event of page.events || []) {
+          const outcome = step(event, { own });
+          if (outcome === 'replayed') continue;
+          if (outcome === 'applied') counts.applied += 1;
+          else if (outcome === 'own' || outcome === 'not_forward') counts.skipped += 1;
+          else if (outcome === 'deferred') counts.deferred += 1;
+          else if (outcome === 'quarantined') counts.quarantined += 1;
+          else if (outcome === 'not_local') counts.notLocal += 1;
+          if (outcome !== 'deferred') settle(event, outcome);
+          else q.record.run(event.seq, event.id || `seq:${event.seq}`, event.type, event.key || '', event.machineId ?? null, 'deferred', now());
+          if (outcome === 'applied' && event.type === 'post.created') counts.posts.push(event);
+          checkpoint('after-event');
+        }
+        q.cursor.run(Number(page.next) || 0, Number(page.head) || 0, Number(page.floor) || 0, now());
+        // Other machines' beats: whose aliases and sessions are live there (Pulse 1.1.1 F1, bus identity).
+        counts.presence = applyRemotePresence(db, page.presence, machineId);
+      });
+      return { ...counts, next: Number(page.next) || 0 };
+    },
+
+    /** Deferred foreign changes whose entity has nothing pending any more: applied now if they are the later write. */
+    retryDeferred() {
+      const counts = { applied: 0, superseded: 0, waiting: 0 };
+      capture.applying(() => {
+        for (const row of q.deferred.all()) {
+          if (q.pending.get(row.grp)) { counts.waiting += 1; continue; }
+          const event = JSON.parse(row.event);
+          const outcome = step(event, { retry: true });
+          if (outcome === 'deferred') { counts.waiting += 1; continue; }
+          q.undefer.run(row.seq);
+          db.prepare('UPDATE pulse_events SET outcome = ? WHERE seq = ?').run(outcome, event.seq);
+          if (outcome === 'applied') { counts.applied += 1; settle(event, outcome); }
+          if (outcome === 'superseded') counts.superseded += 1;
+        }
+      });
+      if (counts.applied) log('deferred_applied', counts);
+      return counts;
+    },
+  };
+}

package/src/runner/bridge.js

@@ -0,0 +1,289 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fullJitterDelay } from '../lib/backoff.js';
+import { scopeBlock } from '../lib/errors.js';
+import { OUTBOX_MAX_PENDING } from '../lib/runnerStore.js';
+import { OutboxFlusher } from '../lib/outboxFlusher.js';
+
+const ONLINE_MS = 35_000;
+const OFFLINE_MS = 60_000;
+const LAG_EVENTS = 50;
+const WAKE_GAP_MS = 30_000;
+const FLUSH_EVERY_MS = 1_000;
+const HEALTH_EVERY_MS = 5_000;
+const BATCHES_PER_FLUSH = 30;
+/** The Phase 2 scanner's file sources (channel.md, personas.json, state/chat) and presence, as the shadow ran them. */
+export const FILE_SOURCES = Object.freeze(['personas', 'chat', 'channels', 'presence']);
+const FILE_SCAN_MS = 10_000;
+/** The manager lease (Q9): renewed well inside its ttl; this machine stops counting on it `LEASE_MARGIN_MS` early. */
+export const LEASE_TTL_MS = 30_000;
+const LEASE_RENEW_MS = 10_000;
+const LEASE_MARGIN_MS = 5_000;
+/** runner.db meta key of the cloud's presence keyset cursor (S3), kept beside the event cursor and sent on every sync. */
+const PRESENCE_CURSOR = 'presence_cursor';
+/** This many sync failures in a row (no page applied in between) and health says so, ahead of anything milder. */
+export const SYNC_FAILING_AFTER = 3;
+/** SCOPE-02: while blocked for a scope or grant, the sync is retried this often with the sign-in read again, so a re-login clears it. */
+export const BLOCK_RETRY_MS = 60_000;
+const ERROR_CODES = new Set(['HUB_LOGIN_REQUIRED', 'HUB_SCOPE_DENIED', 'capability_denied', 'cloud_first_off', 'HUB_MACHINE_REVOKED']);
+
+/**
+ * The daemon's half of the runner (design §6.3): it holds the cloud credentials, so it long-polls `/connector/sync`
+ * and hands each page to the runner process to apply, and it flushes runner.db's outbox to `/connector/commands`.
+ * Outbound only. The cursor it asks from is the one the runner committed with the page it applied (I2), read back
+ * from runner.db, so a crash anywhere re-asks for the same page. Health (§9.4) is measured here and sent to the
+ * runner for the facade, `pulse status` and the cloud.
+ */
+export class RunnerBridge {
+  constructor({
+    runner, transport, store, machineId = null, now = Date.now, monotonic = () => performance.now(), random = Math.random, waitSeconds = 20, log = () => {},
+    lease = { ttlMs: LEASE_TTL_MS, renewMs: LEASE_RENEW_MS, marginMs: LEASE_MARGIN_MS }, fileScan = null, fileScanMs = FILE_SCAN_MS, blockRetryMs = BLOCK_RETRY_MS,
+    flusher = new OutboxFlusher({ store, transport, random }),
+  }) {
+    this.runner = runner;
+    this.transport = transport;
+    this.store = store;
+    this.now = now;
+    this.monotonic = monotonic;
+    this.random = random;
+    this.waitSeconds = waitSeconds;
+    this.log = log;
+    this.flusher = flusher;
+    this.machineId = machineId;
+    this.leaseConfig = lease;
+    this.leaseDeadline = 0;
+    this.fileScan = fileScan;
+    this.fileScanMs = fileScanMs;
+    this.blockRetryMs = blockRetryMs;
+    this.running = false;
+    this.kicked = null;
+    this.state = { lastSyncAt: null, lastContactAt: null, failures: 0, syncFailure: null, error: null, resync: null, head: 0, sleptAt: null, flushError: null };
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.runner.on('wrote', () => this.kick());
+    this.syncing = this.#syncLoop();
+    this.flushing = this.#flushLoop();
+    if (this.leaseConfig) this.leasing = this.#leaseLoop();
+    if (this.fileScan) this.scanning = this.#fileLoop();
+    this.healthTimer = setInterval(() => this.#pushHealth(), HEALTH_EVERY_MS);
+    this.healthTimer.unref?.();
+    this.#pushHealth();
+  }
+
+  async stop() {
+    this.running = false;
+    clearInterval(this.healthTimer);
+    this.kick();
+    this.leaseWake?.();
+    this.fileWake?.();
+    await Promise.allSettled([this.syncing, this.flushing, this.leasing, this.scanning]);
+    if (this.leaseConfig && this.leaseDeadline > this.monotonic()) {
+      await this.#claimLease({ release: true }).catch(() => {});
+      this.runner.send({ type: 'lease', held: false });
+    }
+  }
+
+  /** A local write landed: flush now instead of at the next tick. */
+  kick() {
+    const wake = this.kicked;
+    this.kicked = null;
+    wake?.();
+  }
+
+  applied() {
+    return Number(this.store.db.prepare('SELECT applied_seq FROM pulse_sync WHERE one = 1').get()?.applied_seq || 0);
+  }
+
+  async #syncLoop() {
+    let lastWall = this.now();
+    let lastMono = this.monotonic();
+    let lagging = true;
+    while (this.running) {
+      const wallGap = this.now() - lastWall;
+      const monoGap = this.monotonic() - lastMono;
+      if (wallGap - monoGap > WAKE_GAP_MS) {
+        this.state.sleptAt = this.now();
+        this.log('runner_woke', { asleepMs: Math.round(wallGap - monoGap) });
+        lagging = true;
+      }
+      lastWall = this.now();
+      lastMono = this.monotonic();
+      const blocked = this.state.error?.block ? this.state.error : null;
+      if (this.state.resync || (this.state.error && !blocked)) { await sleep(5_000); continue; }
+      if (blocked) {
+        const left = blocked.at + this.blockRetryMs - this.now();
+        if (left > 0) { await sleep(Math.min(5_000, left)); continue; }
+        this.transport.auth?.invalidate?.();
+      }
+      try {
+        const since = this.applied();
+        const presence = this.store.meta?.(PRESENCE_CURSOR) ?? null;
+        const page = await this.transport.sync({ since, wait: lagging ? 0 : this.waitSeconds, ...(presence ? { presence } : {}) });
+        this.state.lastContactAt = this.now();
+        const result = await this.runner.request({ type: 'apply', page });
+        this.state.lastSyncAt = this.now();
+        if (blocked) {
+          this.state.error = null;
+          this.log('sync_unblocked', { code: blocked.code });
+          this.#pushHealth();
+        }
+        if (typeof page.presenceNext === 'string' && page.presenceNext && page.presenceNext !== presence) this.store.setMeta?.(PRESENCE_CURSOR, page.presenceNext);
+        this.state.failures = 0;
+        this.state.syncFailure = null;
+        this.state.head = Number(page.head) || 0;
+        lagging = Number(page.head) > Number(result.next);
+        if (result.quarantined) this.log('sync_quarantined', { count: result.quarantined, next: result.next });
+      } catch (error) {
+        if (!this.running) break;
+        if (error.code === 'runner_exited') { await sleep(1_000); continue; }
+        if (error.status === 410 || error.code === 'resync_required') {
+          this.state.resync = { at: this.now(), floor: error.details?.floor ?? null };
+          this.log('sync_resync_required', { since: this.applied() });
+          continue;
+        }
+        // A cursor the cloud refuses (after a downgrade, say) would fail every sync: drop it and start presence over.
+        if (error.code === 'invalid_presence' && this.store.meta?.(PRESENCE_CURSOR)) {
+          this.store.setMeta?.(PRESENCE_CURSOR, null);
+          this.log('presence_cursor_reset', { code: error.code });
+          continue;
+        }
+        if (ERROR_CODES.has(error.code)) {
+          this.state.error = { code: error.code, at: this.now(), block: scopeBlock(error) };
+          this.log('sync_refused', { code: error.code });
+          this.#pushHealth();
+          continue;
+        }
+        this.state.failures += 1;
+        this.state.syncFailure = { code: error.code || 'error', at: this.now() };
+        this.log('sync_failed', { code: error.code || 'error', failures: this.state.failures });
+        await sleep(Math.max(1_000, fullJitterDelay(this.state.failures, { capMs: 30_000, random: this.random })));
+      }
+    }
+  }
+
+  async #flushLoop() {
+    let failures = 0;
+    while (this.running) {
+      try {
+        const tally = await this.flusher.drain({ maxBatches: BATCHES_PER_FLUSH });
+        this.state.lastContactAt = tally.batches ? this.now() : this.state.lastContactAt;
+        this.state.flushError = null;
+        failures = 0;
+        if (tally.written + tally.duplicate > 0) await this.runner.request({ type: 'retryDeferred' }).catch(() => {});
+      } catch (error) {
+        failures += 1;
+        this.state.flushError = { code: error.code || 'error', at: this.now() };
+        if (ERROR_CODES.has(error.code)) this.state.error = { code: error.code, at: this.now(), block: scopeBlock(error) };
+        await sleep(Math.max(1_000, fullJitterDelay(failures, { capMs: 30_000, random: this.random })));
+        continue;
+      }
+      await Promise.race([sleep(FLUSH_EVERY_MS), new Promise((resolve) => { this.kicked = resolve; })]);
+    }
+  }
+
+  /**
+   * After cutover the hub.db sources are captured in the runner; the file sources stay with the Phase 2 scanner, now
+   * reading runner.db: channel.md posts agents append, personas, project chat, and presence beats (not log events).
+   */
+  async #fileLoop() {
+    while (this.running) {
+      try {
+        const report = await this.fileScan.run({ mode: 'shadow', sources: FILE_SOURCES });
+        for (let start = 0; start < report.presence.length; start += 100) {
+          const chunk = report.presence.slice(start, start + 100);
+          const answer = await this.transport.commands({ commands: chunk });
+          chunk.forEach((beat, index) => {
+            if (!answer?.results?.[index]?.error) this.store.setPresenceSent(beat.payload.actorId, beat.payload.at);
+          });
+        }
+        if (report.totals.planned) this.kick();
+      } catch (error) {
+        this.log('file_scan_failed', { code: error.code || 'error', message: String(error.message).slice(0, 200) });
+      }
+      await Promise.race([sleep(this.fileScanMs), new Promise((resolve) => { this.fileWake = resolve; })]);
+    }
+  }
+
+  /** One lease call through /commands (no seq). Resolves with the lease, or throws. */
+  async #claimLease({ release = false } = {}) {
+    const payload = release ? { role: 'manager', release: true } : { role: 'manager', ttlMs: this.leaseConfig.ttlMs };
+    const answer = await this.transport.commands({ commands: [{ type: 'runner.lease', idempotencyKey: `lease:${this.machineId || 'runner'}:${this.now()}`, payload }] });
+    const result = answer?.results?.[0];
+    if (!result || result.error) throw Object.assign(new Error(result?.error?.message || 'no lease result'), { code: result?.error?.code || 'lease_failed' });
+    return result.lease;
+  }
+
+  /**
+   * Claims or renews the manager lease every renewMs. The deadline is the monotonic time the winning request was sent,
+   * plus the ttl, minus a margin: never the cloud's `until` against this machine's clock (H4). A failed renew keeps the
+   * deadline it had; when it passes, the runner is told at once and stops its manager before the cloud lets anyone else in.
+   */
+  async #leaseLoop() {
+    const { ttlMs, renewMs, marginMs } = this.leaseConfig;
+    let lapse = null;
+    const report = (lease) => {
+      const remainingMs = Math.max(0, this.leaseDeadline - this.monotonic());
+      this.runner.send({ type: 'lease', held: remainingMs > 0, remainingMs, holder: lease?.holder ?? null, fence: lease?.fence ?? 0 });
+    };
+    while (this.running) {
+      const sentAt = this.monotonic();
+      try {
+        const lease = await this.#claimLease();
+        this.lease = lease;
+        this.leaseDeadline = lease.here ? sentAt + ttlMs - marginMs : 0;
+        report(lease);
+      } catch (error) {
+        this.log('lease_failed', { code: error.code || 'error' });
+        report(this.lease);
+      }
+      clearTimeout(lapse);
+      const remaining = this.leaseDeadline - this.monotonic();
+      if (remaining > 0) {
+        lapse = setTimeout(() => report(this.lease), remaining);
+        lapse.unref?.();
+      }
+      await Promise.race([sleep(renewMs), new Promise((resolve) => { this.leaseWake = resolve; })]);
+    }
+    clearTimeout(lapse);
+  }
+
+  /** The measured state (§9.4): never "running" alone. */
+  health() {
+    const now = this.now();
+    const pending = this.store.pendingCount();
+    const dead = Number(this.store.db.prepare('SELECT COUNT(*) AS n FROM dead').get().n);
+    const quarantined = Number(this.store.db.prepare('SELECT COUNT(*) AS n FROM pulse_quarantine').get()?.n || 0);
+    const applied = this.applied();
+    const lag = Math.max(0, this.state.head - applied);
+    const outbox = { pending, dead, capacity: OUTBOX_MAX_PENDING };
+    const base = { lastSyncAt: this.state.lastSyncAt, applied, head: this.state.head, lag, outbox, quarantined,
+      staleSeconds: this.state.lastSyncAt ? (now - this.state.lastSyncAt) / 1000 : null };
+    const { block } = this.state.error || {};
+    if (block) {
+      const missing = block.missingScopes.length ? `missing ${block.missingScopes.join(', ')}` : 'missing a scope or capability';
+      return { ...base, state: 'blocked', reason: `${block.code}: ${missing}`, code: block.code, missingScopes: block.missingScopes, fix: block.fix };
+    }
+    if (this.state.error) return { ...base, state: 'error', reason: this.state.error.code, fix: this.state.error.code === 'HUB_LOGIN_REQUIRED' ? 'agentpulse login' : null };
+    if (this.state.resync) return { ...base, state: 'error', reason: 'resync_required' };
+    if (this.state.failures >= SYNC_FAILING_AFTER && this.state.syncFailure) {
+      const { code } = this.state.syncFailure;
+      return { ...base, state: 'degraded', reason: `sync failing (${code})`, code, failures: this.state.failures };
+    }
+    if (this.state.sleptAt && (!this.state.lastSyncAt || this.state.lastSyncAt < this.state.sleptAt)) return { ...base, state: 'sleeping', reason: 'woke from sleep, catching up' };
+    if (!this.state.lastContactAt || now - this.state.lastContactAt > OFFLINE_MS) {
+      return { ...base, state: 'offline', reason: this.state.lastContactAt ? 'no contact with Pulse' : 'not connected yet' };
+    }
+    if (lag > LAG_EVENTS || (pending > 0 && this.state.flushError)) return { ...base, state: 'catching_up', reason: `${lag} events and ${pending} changes to go` };
+    if (dead || quarantined || pending > 0.8 * OUTBOX_MAX_PENDING) {
+      return { ...base, state: 'degraded', reason: `${dead} change${dead === 1 ? '' : 's'} and ${quarantined} event${quarantined === 1 ? '' : 's'} set aside` };
+    }
+    if (!this.state.lastSyncAt || now - this.state.lastSyncAt > ONLINE_MS) return { ...base, state: 'catching_up', reason: 'waiting for a sync' };
+    return { ...base, state: 'online', reason: 'in sync' };
+  }
+
+  #pushHealth() {
+    try { this.runner.send({ type: 'health', health: this.health() }); } catch (error) { this.log('health_failed', { code: error.code || 'error' }); }
+  }
+}