@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/lib/shadowService.js

@@ -0,0 +1,435 @@
+import { appendFile, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { HubError, scopeBlock } from './errors.js';
+import { HubDbReader } from './hubDbReader.js';
+import { HubScan } from './hubScan.js';
+import { SNAPSHOT_DIR, takeSnapshot } from './hubSnapshot.js';
+import { discoverLocalHub, LocalHubReader } from './localHub.js';
+import { OutboxFlusher } from './outboxFlusher.js';
+import { pairedStatus } from './pairedConfig.js';
+import {
+  channelOnDisk, cloudOnlyChannels, compareReconcile, driftTexts, itemId, localReconcile, redactionCandidates, resolvePostKeys, sourceCounts,
+} from './reconcile.js';
+import { REDACTION_ROOTS_META, RunnerStore } from './runnerStore.js';
+import { UploadRedactor } from './uploadRedactor.js';
+
+export const IMPORT_REQUEST_FILE = 'import.request';
+export const PARITY_REQUEST_FILE = 'parity.request';
+export const PARITY_LOG_FILE = 'parity.log';
+export const RECONCILE_REQUEST_FILE = 'reconcile.request';
+export const RECONCILE_REPORT_FILE = 'reconcile-last.json';
+export const HUB_CHANNEL_DIRS = Object.freeze(['AgentPulseApps', 'Google_Cloud']);
+const TICK_MS = 10_000;
+const FLAG_FRESH_MS = 60_000;
+const BLOCKED_BASE_MS = 60_000;
+const BLOCKED_CAP_MS = 15 * 60_000;
+const PARITY_EVERY_MS = 15 * 60_000;
+const BATCHES_PER_TICK = 30;
+// A redaction proof tries an item's own candidates one by one only up to this many; past it the item stays drift.
+const REDACTION_TRIES = 6;
+const SENT_KEEP_MS = 30 * 86_400_000;
+const REFUSALS = new Set(['cloud_first_off', 'capability_denied', 'HUB_SCOPE_DENIED', 'HUB_LOGIN_REQUIRED']);
+
+export function shadowEnabled(config) {
+  return config?.cloudFirst?.shadow === true;
+}
+
+/** The service runs for an import (and its reconcile) without the shadow; it tails only with `shadow` on. */
+export function importEnabled(config) {
+  return shadowEnabled(config) || config?.cloudFirst?.import === true;
+}
+
+/** The hub's own channel roots (agents-hub server/http.mjs CHANNEL_ROOTS), unless the config names others. */
+export function channelRoots(config, hubDir) {
+  const configured = config?.cloudFirst?.channelRoots;
+  if (Array.isArray(configured) && configured.length && configured.every((root) => typeof root === 'string' && path.isAbsolute(root))) return configured;
+  return HUB_CHANNEL_DIRS.map((dir) => path.join(path.resolve(hubDir, '..'), dir));
+}
+
+async function readRequest(file) {
+  try {
+    const value = JSON.parse(await readFile(file, 'utf8'));
+    return Number.isFinite(value?.requestedAt) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The import and shadow feed (cloud-first Phase 2, ADR-4). An import is asked for with import.request in the config
+ * directory and runs here, on the daemon's own connector session: it snapshots the hub's sources (hubSnapshot.js) and
+ * sends the snapshot to the Pulse log through runner.db. A reconcile (reconcile.request) rescans that snapshot into an
+ * empty store and compares it with the cloud's reconcile view. Both run with `cloudFirst.import` or `cloudFirst.shadow`
+ * on and the team's cloud-first flag on in Pulse. Only with `shadow` on does it then tail the live hub (after an
+ * import has fully drained, `imported_at`, so an import can never land an older value after a newer one), fetching a
+ * parity report every 15 minutes (or on parity.request) into parity.log. The shadow is for cutover only.
+ */
+export class ShadowService {
+  constructor({
+    directory, transportFactory, tokenStore = null, discover = discoverLocalHub, openStore = (dir) => RunnerStore.open(dir),
+    home = os.homedir(), now = Date.now, tickMs = TICK_MS, log = () => {}, random = Math.random,
+  }) {
+    this.directory = directory;
+    this.transportFactory = transportFactory;
+    this.tokenStore = tokenStore;
+    this.discover = discover;
+    this.openStore = openStore;
+    this.home = home;
+    this.now = now;
+    this.tickMs = tickMs;
+    this.log = log;
+    this.random = random;
+    this.config = null;
+    this.store = null;
+    this.timer = null;
+    this.running = null;
+    this.flag = null;
+    this.blocked = null;
+    this.refusals = 0;
+    this.lastParityAt = -Infinity;
+    this.state = { state: 'off' };
+  }
+
+  /** The heartbeat's config; starts, stops or keeps the loop. Never waits on a pass. */
+  update(config) {
+    this.config = config;
+    const on = importEnabled(config) && pairedStatus(config).ok;
+    if (on && !this.timer && !this.running) this.#schedule(0);
+    if (!on && (this.timer || this.running)) void this.stop();
+    if (!on) this.state = { state: 'off' };
+    return this.state;
+  }
+
+  async stop() {
+    clearTimeout(this.timer);
+    this.timer = null;
+    await this.running;
+    this.store?.close();
+    this.store = null;
+    this.state = { state: 'off' };
+  }
+
+  #schedule(waitMs) {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.running = this.tick().finally(() => {
+        this.running = null;
+        if (importEnabled(this.config) && pairedStatus(this.config).ok) this.#schedule(this.#nextWait());
+      });
+    }, waitMs);
+    this.timer.unref?.();
+  }
+
+  #nextWait() {
+    return this.blocked ? Math.max(0, this.blocked.retryAt - this.now()) : this.tickMs;
+  }
+
+  /** One pass: flag, import (or reconcile) or shadow scan, flush, presence, parity. Never rejects. */
+  async tick() {
+    try {
+      const config = this.config;
+      this.store ??= await this.openStore(this.directory);
+      const request = await readRequest(path.join(this.directory, IMPORT_REQUEST_FILE));
+      const reconcile = await readRequest(path.join(this.directory, RECONCILE_REQUEST_FILE));
+      const imported = this.store.meta('imported_at');
+      let job = this.store.meta('import');
+      const asked = (request && job?.requestedAt !== request.requestedAt) || job?.phase === 'sending' || reconcile;
+      if (!asked && !shadowEnabled(config)) {
+        this.state = imported ? { state: 'imported', importedAt: imported } : { state: 'waiting_for_import' };
+        await this.#persistState();
+        return this.state;
+      }
+      const transport = await this.transportFactory(config);
+      // Blocked for scopes: the retry reads the stored sign-in again, so a `pulse login` since is what it sends.
+      if (this.blocked?.scope) transport.auth?.invalidate?.();
+      if (!(await this.#flagOn(transport))) return this.state;
+      const hub = await this.discover({ config });
+      this.hubToken ??= await new LocalHubReader({ dir: hub.dir, port: hub.port }).tokenValue().catch(() => null);
+      const flusher = new OutboxFlusher({ store: this.store, transport, random: this.random });
+      if (request && job?.requestedAt !== request.requestedAt) {
+        this.state = { state: 'importing', phase: 'scanning', requestedAt: request.requestedAt };
+        await this.#persistState();
+        const snapshot = request.reuseSnapshot && job?.snapshot
+          ? job.snapshot
+          : await takeSnapshot({ hubDir: hub.dir, roots: channelRoots(config, hub.dir), into: path.join(this.directory, SNAPSHOT_DIR), now: this.now });
+        const before = this.store.counts();
+        const scan = this.#scanner({ store: this.store, hub, config, transport, snapshot });
+        const report = await scan.run({ mode: 'import' });
+        this.#keepRoots(scan);
+        job = {
+          requestedAt: request.requestedAt, phase: 'sending', startedAt: this.now(), scan: summary(report), before, presence: report.presence.length,
+          snapshot: snapshotRef(snapshot), reusedSnapshot: Boolean(request.reuseSnapshot && job?.snapshot),
+        };
+        this.store.setMeta('import', job);
+        await this.#beats(transport, report.presence);
+      }
+      if (job?.phase === 'sending') {
+        const sent = await flusher.drain({ maxBatches: BATCHES_PER_TICK });
+        if (this.store.pendingCount() === 0) {
+          job = { ...job, phase: 'done', finishedAt: this.now(), after: this.store.counts() };
+          this.store.setMeta('import', job);
+          if (!imported) this.store.setMeta('imported_at', job.finishedAt);
+          await rm(path.join(this.directory, IMPORT_REQUEST_FILE), { force: true });
+        }
+        this.state = { state: 'importing', phase: job.phase, requestedAt: job.requestedAt, pending: this.store.pendingCount(), lastBatch: sent };
+      } else if (reconcile) {
+        await this.#reconcile({ hub, config, transport, job, request: reconcile });
+      } else if (this.store.meta('imported_at')) {
+        const scan = this.#scanner({ store: this.store, hub, config, transport });
+        const report = await scan.run({ mode: 'shadow' });
+        this.#keepRoots(scan);
+        await this.#beats(transport, report.presence);
+        const sent = await flusher.drain({ maxBatches: BATCHES_PER_TICK });
+        this.store.pruneSent(this.now() - SENT_KEEP_MS);
+        this.state = { state: 'running', lastPassAt: this.now(), planned: report.totals.planned, pending: this.store.pendingCount(), lastBatch: sent };
+        await this.#parity(transport);
+      } else {
+        this.state = { state: 'waiting_for_import' };
+      }
+      this.blocked = null;
+      this.refusals = 0;
+    } catch (error) {
+      this.#fail(error);
+    }
+    await this.#persistState();
+    return this.state;
+  }
+
+  async #flagOn(transport) {
+    if (!this.flag || this.now() - this.flag.at >= FLAG_FRESH_MS) {
+      const answer = await transport.cloudFirst();
+      this.flag = { enabled: answer?.enabled === true, at: this.now() };
+    }
+    if (this.flag.enabled) return true;
+    throw new HubError('cloud_first_off', 'Pulse cloud-first is off for this team');
+  }
+
+  /**
+   * A scanner over the live hub (the shadow tail) or over a snapshot of it (an import, a reconcile). Either way the
+   * redaction is the live workspace's, so a snapshot scans to the very commands the live sources would. It starts from
+   * every repo and worktree root kept in the live store (learned before, or proven by a reconcile), so a worktree whose
+   * delivery is gone still redacts as it did when its text was sent. `seed` adds candidate roots to a scratch scan.
+   */
+  #scanner({ store, hub, config, transport, snapshot = null, seed = null }) {
+    const key = `${hub.dir}\0${snapshot?.dir ?? ''}\0${store === this.store}`;
+    let scan = this.scanners?.key === key ? this.scanners.scan : null;
+    if (!scan) {
+      const approvedRoots = (config.localRoots || []).map((root) => root.canonicalRoot).filter(Boolean).sort();
+      const sourceDir = snapshot?.snapshotHubDir ?? hub.dir;
+      scan = new HubScan({
+        store,
+        reader: new HubDbReader({ hubDir: sourceDir }),
+        hubDir: sourceDir,
+        roots: snapshot?.snapshotRoots ?? channelRoots(config, hub.dir),
+        redaction: new UploadRedactor({ workspace: path.dirname(hub.dir), home: this.home, approvedRoots }),
+        secrets: () => [this.hubToken, ...(transport.auth?.heldSecrets?.() ?? [])],
+        now: this.now,
+      });
+      if (store === this.store) this.scanners = { key, scan };
+    }
+    scan.redaction.seed(this.store.meta(REDACTION_ROOTS_META));
+    if (seed) scan.redaction.seed(seed);
+    return scan;
+  }
+
+  /** The roots a pass over the live store learned join the kept ones (written only when they grew). */
+  #keepRoots(scan) {
+    scan.redaction.seed(this.store.meta(REDACTION_ROOTS_META));
+    const roots = scan.redaction.roots();
+    if (JSON.stringify(roots) !== JSON.stringify(this.store.meta(REDACTION_ROOTS_META))) this.store.setMeta(REDACTION_ROOTS_META, roots);
+  }
+
+  /**
+   * The snapshot rescanned into an empty scratch store, as the reconcile's local side: posts keyed as first sent.
+   * `seed` adds redaction roots and `only` limits it to a few channels and conversations (a redaction proof).
+   */
+  async #rescan({ hub, config, transport, job, seed = null, only = null }) {
+    const scratch = await mkdtemp(path.join(this.directory, 'reconcile-'));
+    try {
+      const store = await this.openStore(scratch);
+      try {
+        const report = await this.#scanner({ store, hub, config, transport, snapshot: job.snapshot, seed }).run({ mode: 'import', only });
+        const commands = resolvePostKeys(store.planned(), (channel, sha) => this.store.ingestedKey(channel, sha));
+        return { report, local: localReconcile({ commands, dead: store.deadKeys() }) };
+      } finally {
+        store.close();
+      }
+    } finally {
+      await rm(scratch, { recursive: true, force: true });
+    }
+  }
+
+  /**
+   * CUT-02 (the 12:44:58 DECISION): which drifted items Pulse holds in a more-redacted form of the same text. The
+   * candidates are the deleted directories each item's own text names (`redactionCandidates`). An item is proven only
+   * when a rescan of it with candidates added gives exactly the cloud's sha: all candidates first, then the item's
+   * own, then each of those alone. Returns the proven items' ids with the roots each match took: an item proven by
+   * all candidates keeps only its own if they alone match again, else all of them.
+   */
+  async #proveRedaction({ hub, config, transport, job, drift, cloud }) {
+    const texts = await driftTexts(job.snapshot, drift);
+    const workspace = path.dirname(hub.dir);
+    const own = new Map();
+    for (const entry of drift) own.set(itemId(entry.family, entry.item), await redactionCandidates({ texts: texts.get(itemId(entry.family, entry.item)) ?? [], workspace }));
+    const matching = async (entries, roots) => {
+      if (!roots.length) return [];
+      const only = { channels: new Set(), topics: new Set() };
+      for (const entry of entries) (entry.family === 'posts.byChannel' ? only.channels : only.topics).add(entry.item);
+      const { local } = await this.#rescan({ hub, config, transport, job, seed: { worktree: roots.map((root) => [root, path.basename(root)]) }, only });
+      return entries.filter((entry) => {
+        const [view, theirs] = entry.family === 'posts.byChannel'
+          ? [local.view.posts.byChannel, cloud.view.posts.byChannel] : [local.view.messages.byTopic, cloud.view.messages.byTopic];
+        return Boolean(view[entry.item]) && view[entry.item].sha === theirs[entry.item]?.sha;
+      });
+    };
+    const proven = new Map();
+    const all = [...new Set([...own.values()].flat())].sort();
+    for (const entry of await matching(drift, all)) {
+      const mine = own.get(itemId(entry.family, entry.item));
+      const alone = mine.length && mine.length < all.length ? (await matching([entry], mine)).length > 0 : mine.length === all.length;
+      proven.set(itemId(entry.family, entry.item), alone ? mine : all);
+    }
+    for (const entry of drift) {
+      const mine = own.get(itemId(entry.family, entry.item));
+      if (proven.has(itemId(entry.family, entry.item)) || mine.length > REDACTION_TRIES) continue;
+      for (const roots of [mine, ...(mine.length > 1 ? mine.map((root) => [root]) : [])]) {
+        if ((await matching([entry], roots)).length) {
+          proven.set(itemId(entry.family, entry.item), roots);
+          break;
+        }
+      }
+    }
+    return proven;
+  }
+
+  /**
+   * ADR-4: rescan the last import's snapshot into an empty scratch store (a fresh read of the sources with the same
+   * scanner, redactor and keys), count the snapshot's rows without the scanner, ask the cloud for its view of this
+   * machine's log, and record the comparison in runner.db and reconcile-last.json. Each post takes the key it was
+   * first sent under, each cloud-only channel is looked for on disk, and drift is checked for redaction (CUT-02); the
+   * roots a redaction proof took are kept, so later scans redact as Pulse holds it. Nothing is sent.
+   */
+  async #reconcile({ hub, config, transport, job, request }) {
+    this.state = { state: 'reconciling', requestedAt: request.requestedAt };
+    await this.#persistState();
+    const requestFile = path.join(this.directory, RECONCILE_REQUEST_FILE);
+    let result;
+    if (!job?.snapshot || job.phase !== 'done') {
+      result = { status: 'no_import', message: 'Run `agentpulse pulse import` to completion first; the reconcile rescans its snapshot.' };
+    } else {
+      const { report, local } = await this.#rescan({ hub, config, transport, job });
+      const counts = await sourceCounts({ hubDir: job.snapshot.snapshotHubDir, roots: job.snapshot.snapshotRoots });
+      const cloud = await transport.parity({ view: 'reconcile' });
+      const roots = channelRoots(config, hub.dir);
+      const onDisk = {};
+      for (const channel of cloudOnlyChannels(local, cloud)) onDisk[channel] = await channelOnDisk(channel, roots);
+      let compared = compareReconcile({ local, cloud, counts, report, sent: this.store, onDisk });
+      if (compared.drift.length) {
+        const redacted = await this.#proveRedaction({ hub, config, transport, job, drift: compared.drift, cloud });
+        compared = compareReconcile({ local, cloud, counts, report, sent: this.store, onDisk, redacted });
+        const matched = [...new Set([...redacted.values()].flat())];
+        if (matched.length) {
+          const kept = new UploadRedactor({ workspace: path.dirname(hub.dir), home: this.home });
+          kept.seed(this.store.meta(REDACTION_ROOTS_META));
+          kept.seed({ worktree: matched.map((root) => [root, path.basename(root)]) });
+          this.store.setMeta(REDACTION_ROOTS_META, kept.roots());
+        }
+      }
+      const sent = this.store.counts();
+      result = {
+        status: compared.status,
+        snapshotTakenAt: job.snapshot.takenAt,
+        head: cloud.head,
+        compared: cloud.compared,
+        otherWriters: cloud.otherWriters,
+        sources: compared.sources,
+        imported: Object.fromEntries(Object.entries(sent).map(([source, row]) => [source, { written: row.written, duplicate: row.duplicate, setAside: row.dead }])),
+        families: familyTable(local.view, cloud.view),
+        classes: compared.classes,
+        retired: compared.retired,
+        redacted: compared.redacted,
+        withheld: local.withheld,
+        cut: local.cut,
+        mismatches: compared.mismatches,
+      };
+    }
+    const recorded = { ...result, at: this.now(), requestedAt: request.requestedAt };
+    this.store.setMeta('reconcile_last', recorded);
+    await writeFile(path.join(this.directory, RECONCILE_REPORT_FILE), `${JSON.stringify(recorded, null, 1)}\n`, { mode: 0o600 });
+    await rm(requestFile, { force: true });
+    this.state = { state: 'reconciled', status: result.status, at: recorded.at };
+  }
+
+  /** Presence beats ride straight to the cloud (they are not events and are coalesced there); sent ones are recorded. */
+  async #beats(transport, beats) {
+    for (let start = 0; start < beats.length; start += 100) {
+      const chunk = beats.slice(start, start + 100);
+      const answer = await transport.commands({ commands: chunk });
+      chunk.forEach((beat, index) => {
+        if (!answer?.results?.[index]?.error) this.store.setPresenceSent(beat.payload.actorId, beat.payload.at);
+      });
+    }
+  }
+
+  async #parity(transport) {
+    const requestFile = path.join(this.directory, PARITY_REQUEST_FILE);
+    const request = await readRequest(requestFile);
+    if (!request && this.now() - this.lastParityAt < PARITY_EVERY_MS) return;
+    this.lastParityAt = this.now();
+    const hours = Number(request?.hours) || 6;
+    const report = await transport.parity({ hours });
+    const line = { at: this.now(), hours, status: report.status, percent: report.percent, totals: report.totals, families: report.families };
+    this.store.setMeta('parity_last', { ...line, diffs: (report.diffs || []).slice(0, 50), requestedAt: request?.requestedAt ?? null });
+    await appendFile(path.join(this.directory, PARITY_LOG_FILE), `${JSON.stringify(line)}\n`, { mode: 0o600 });
+    if (request) await rm(requestFile, { force: true });
+  }
+
+  #fail(error) {
+    const code = error.code || 'HUB_SHADOW_FAILED';
+    if (REFUSALS.has(code)) {
+      const waitMs = Math.min(BLOCKED_CAP_MS, BLOCKED_BASE_MS * 2 ** this.refusals);
+      this.refusals += 1;
+      const scope = scopeBlock(error);
+      this.blocked = { code, retryAt: this.now() + waitMs, scope: Boolean(scope) };
+      if (code === 'cloud_first_off') this.flag = null;
+      this.state = { state: 'blocked', code, retryAt: new Date(this.blocked.retryAt).toISOString(), ...(scope ? { missingScopes: scope.missingScopes, fix: scope.fix } : {}) };
+    } else {
+      this.state = { state: 'error', code };
+    }
+    this.log('shadow_failed', { code });
+  }
+
+  async #persistState() {
+    try {
+      this.store?.setMeta('shadow_state', { ...this.state, at: this.now() });
+    } catch {
+      // A store that cannot take the state still runs; status reads the last one written.
+    }
+  }
+
+  /** What health shows: the state with the backlog and set-aside counts. */
+  health() {
+    if (!this.store) return this.state;
+    const dead = Object.values(this.store.counts()).reduce((sum, source) => sum + Object.values(source.dead).reduce((n, v) => n + v, 0), 0);
+    return { ...this.state, pending: this.store.pendingCount(), setAside: dead };
+  }
+}
+
+function summary(report) {
+  return { totals: report.totals, sources: report.sources };
+}
+
+function snapshotRef(snapshot) {
+  return { dir: snapshot.dir, takenAt: snapshot.takenAt, files: snapshot.files, snapshotHubDir: snapshot.snapshotHubDir, snapshotRoots: snapshot.snapshotRoots };
+}
+
+/** Per family: the local count and hash beside the cloud's. */
+function familyTable(local, cloud = {}) {
+  const row = (a = {}, b = {}) => ({ local: a.count ?? null, cloud: b.count ?? null, equal: a.count === b.count && a.sha === b.sha });
+  const out = {};
+  for (const family of ['channels', 'posts', 'messages', 'actors', 'agentRows', 'personas', 'statusOverrides']) out[family] = row(local[family], cloud[family]);
+  for (const kind of Object.keys(local.facts)) out[`facts.${kind}`] = row(local.facts[kind], cloud.facts?.[kind]);
+  return out;
+}

package/src/lib/sqlite.js

@@ -0,0 +1,28 @@
+import { HubError } from './errors.js';
+
+/**
+ * node:sqlite's DatabaseSync, looked up when a store is opened rather than imported, so the daemon and the mirror
+ * still load on a Node without it (before 22.13); only what needs runner.db or hub.db refuses there.
+ */
+export function openDatabase(file, options = {}, getBuiltin = process.getBuiltinModule?.bind(process)) {
+  const sqlite = getBuiltin?.('node:sqlite');
+  if (!sqlite?.DatabaseSync) {
+    throw new HubError('HUB_NODE_TOO_OLD', `The Pulse shadow feed and import need Node 22.13 or later; this is Node ${process.versions.node}`);
+  }
+  return new sqlite.DatabaseSync(file, options);
+}
+
+/**
+ * A consistent copy of a live SQLite file (WAL included) at `to`, read-only on `from`: the online backup API where
+ * this Node has it (22.16 and later), else `VACUUM INTO`, which gives the same transactionally consistent copy.
+ */
+export async function backupDatabase(from, to, getBuiltin = process.getBuiltinModule?.bind(process)) {
+  const sqlite = getBuiltin?.('node:sqlite');
+  const source = openDatabase(from, { readOnly: true }, getBuiltin);
+  try {
+    if (typeof sqlite.backup === 'function') await sqlite.backup(source, to);
+    else source.prepare('VACUUM INTO ?').run(to);
+  } finally {
+    source.close();
+  }
+}

package/src/lib/tokenStore.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { rm } from 'node:fs/promises';
 import path from 'node:path';
 import { HubError } from './errors.js';
@@ -5,7 +6,10 @@ import { acquireOwnerLock } from './ownerLock.js';
 import { ProcessIdentityProvider } from './processOwnership.js';
 import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
 
-const SECRET_REFERENCE = 'oauth-session';
+/** The one name every config used before sign-ins were named per config dir; a config without `secretRef` still uses it. */
+export const LEGACY_SECRET_REFERENCE = 'oauth-session';
+/** This config dir's own sign-in item, so a second config (another XDG_CONFIG_HOME or profile) never overwrites it. */
+export const sessionSecretReference = (configDir) => `oauth-session-${createHash('sha256').update(path.resolve(configDir)).digest('hex').slice(0, 16)}`;
 const METADATA_FILE = 'oauth-session.json';
 const LOCK_FILE = 'oauth-refresh.lock';
 const inProcessLocks = new Map();
@@ -13,16 +17,23 @@ const inProcessLocks = new Map();
 export class TokenStore {
   constructor({ secretStore, configDir, lockTimeoutMs = 10_000, identityProvider = new ProcessIdentityProvider() }) {
     this.secretStore = secretStore;
+    this.ownReference = sessionSecretReference(configDir);
     this.metadataFile = path.join(configDir, METADATA_FILE);
     this.lockFile = path.join(configDir, LOCK_FILE);
     this.lockTimeoutMs = lockTimeoutMs;
     this.identityProvider = identityProvider;
   }
 
+  /** The item a config's sign-in lives in: its recorded one, the legacy one for a config signed in before, else its own. */
+  #reference(metadata) {
+    if (!metadata) return this.ownReference;
+    return metadata.secretRef || LEGACY_SECRET_REFERENCE;
+  }
+
   async load() {
     const metadata = await readOwnerOnlyJson(this.metadataFile);
     if (!metadata) return null;
-    const secret = await this.secretStore.get(SECRET_REFERENCE);
+    const secret = await this.secretStore.get(this.#reference(metadata));
     if (!secret) return null;
     let tokens;
     try {
@@ -52,11 +63,13 @@ export class TokenStore {
     if (typeof session?.accessToken !== 'string' || !session.userId || !session.teamId || !session.platformUrl) {
       throw new HubError('HUB_TOKEN_STORE_INVALID', 'Refusing to store an incomplete Pulse sign-in');
     }
-    await this.secretStore.set(SECRET_REFERENCE, JSON.stringify({
+    const reference = this.#reference(await readOwnerOnlyJson(this.metadataFile));
+    await this.secretStore.set(reference, JSON.stringify({
       accessToken: session.accessToken,
       refreshToken: session.refreshToken ?? null,
     }));
     await writeOwnerOnlyJson(this.metadataFile, {
+      ...(reference === LEGACY_SECRET_REFERENCE ? {} : { secretRef: reference }),
       platformUrl: session.platformUrl,
       userId: session.userId,
       teamId: session.teamId,
@@ -66,10 +79,36 @@ export class TokenStore {
   }
 
   async clear() {
-    await this.secretStore.delete(SECRET_REFERENCE);
+    await this.secretStore.delete(this.#reference(await readOwnerOnlyJson(this.metadataFile)));
     await rm(this.metadataFile, { force: true });
   }
 
+  /** What `migrateSecret` would do, read-only: `{ from, to }` for a legacy sign-in, else null. */
+  async secretPlan() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    return metadata && !metadata.secretRef ? { from: LEGACY_SECRET_REFERENCE, to: this.ownReference } : null;
+  }
+
+  /**
+   * Move a legacy sign-in to this config's own item (at cutover): copy, read it back, record it, and only then remove
+   * the legacy item. Runs under the refresh lock, so a refresh can't write the legacy item in between.
+   */
+  async migrateSecret() {
+    return this.withRefreshLock(async () => {
+      const metadata = await readOwnerOnlyJson(this.metadataFile);
+      if (!metadata || metadata.secretRef) return { moved: false, reference: metadata?.secretRef ?? null };
+      const secret = await this.secretStore.get(LEGACY_SECRET_REFERENCE);
+      if (!secret) return { moved: false, reference: null };
+      await this.secretStore.set(this.ownReference, secret);
+      if ((await this.secretStore.get(this.ownReference)) !== secret) {
+        throw new HubError('HUB_TOKEN_MIGRATION_FAILED', 'The sign-in did not read back from its new Keychain item; the old item is kept');
+      }
+      await writeOwnerOnlyJson(this.metadataFile, { secretRef: this.ownReference, ...metadata });
+      await this.secretStore.delete(LEGACY_SECRET_REFERENCE);
+      return { moved: true, from: LEGACY_SECRET_REFERENCE, to: this.ownReference };
+    });
+  }
+
   async withRefreshLock(action) {
     const previous = inProcessLocks.get(this.lockFile) || Promise.resolve();
     let release;

package/src/lib/transport.js

@@ -1,7 +1,7 @@
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fullJitterDelay } from './backoff.js';
 import { loginRequired } from './cloudAuth.js';
-import { HubError } from './errors.js';
+import { HubError, SCOPE_FIX } from './errors.js';
 import { cleanOrigin, fetchJson } from './http.js';
 import { CONTRACT_HEADER, CONTRACT_VERSION, MIRROR_LIMITS, MIRROR_PATH, parseAccepts } from './mirrorContract.js';
 import { PriorityLane } from './priorityLane.js';
@@ -22,6 +22,9 @@ const MIRROR_TIMEOUT_MS = 30_000;
 const MIRROR_GZIP_ABOVE_BYTES = 8 * 1024;
 // The cloud holds a claim up to waitSeconds before answering; the request waits that long plus this much.
 const CLAIM_TIMEOUT_MARGIN_MS = 10_000;
+// The cloud's PULSE_LIMITS: a command batch holds at most 100 commands in 512 KB.
+const PULSE_MAX_BATCH = 100;
+const PULSE_BODY_BYTES = 512 * 1024;
 
 /**
  * A claimed job with its integers as numbers. The cloud returns agent_hub_jobs rows as node-pg serialises them, so the
@@ -58,7 +61,7 @@ export function contractUnsupported(accepts, message) {
 }
 
 function requestBytes(payload, maxBodyBytes) {
-  if (Buffer.byteLength(JSON.stringify(payload), 'utf8') > maxBodyBytes) {
+  if (payload !== undefined && Buffer.byteLength(JSON.stringify(payload), 'utf8') > maxBodyBytes) {
     throw new HubError('HUB_TRANSPORT_PAYLOAD_TOO_LARGE', `Request exceeds ${maxBodyBytes} bytes`);
   }
 }
@@ -106,7 +109,7 @@ export class ConnectorTransport {
    * reading credentials (a token refresh or dev-org mint), the JSON and wire bytes, and the cloud's Server-Timing of
    * the attempt that answered.
    */
-  async #request(path, payload, { retry = false, maxBodyBytes, timeoutMs = REQUEST_TIMEOUT_MS, gzipAboveBytes, trace = {} }) {
+  async #request(path, payload, { retry = false, maxBodyBytes, timeoutMs = REQUEST_TIMEOUT_MS, gzipAboveBytes, trace = {}, method = 'POST' }) {
     requestBytes(payload, maxBodyBytes);
     trace.attempts = 0;
     trace.statuses = [];
@@ -132,6 +135,7 @@ export class ConnectorTransport {
         response = await fetchJson({
           fetch: this.fetch,
           url: `${this.baseUrl}${path}`,
+          method,
           headers: { ...credentials, ...this.#identityHeaders() },
           body: payload,
           maxBytes: CONNECTOR_RESPONSE_MAX_BYTES,
@@ -163,8 +167,11 @@ export class ConnectorTransport {
         continue;
       }
       if (response.status === 403 && response.body.error === 'FORBIDDEN') {
-        throw new HubError('HUB_SCOPE_DENIED', 'Your Pulse tier does not grant the connector scopes for this operation', {
-          details: { status: 403 },
+        const missingScopes = (Array.isArray(response.body.required) ? response.body.required : []).filter((s) => typeof s === 'string').slice(0, 10).map((s) => s.slice(0, 80));
+        throw new HubError('HUB_SCOPE_DENIED', missingScopes.length
+          ? `The Pulse sign-in lacks ${missingScopes.join(', ')}; run \`${SCOPE_FIX}\``
+          : 'Your Pulse tier does not grant the connector scopes for this operation', {
+          details: { status: 403, missingScopes, fix: SCOPE_FIX },
         });
       }
       if (retry && (response.status === 429 || response.status >= 500)) {
@@ -252,6 +259,47 @@ export class ConnectorTransport {
     }), { path: '/events' });
   }
 
+  /**
+   * One batch of Pulse log commands (`[{ type, idempotencyKey, payload, group? }]`, at most 100), answered per item.
+   * It waits behind heartbeats like a mirror batch. 429 and 5xx are retried with Retry-After; a refusal of the whole
+   * batch (the team's cloud-first flag is off, a missing capability) is thrown with the cloud's code.
+   */
+  commands(payload) {
+    if (!Array.isArray(payload?.commands) || payload.commands.length < 1 || payload.commands.length > PULSE_MAX_BATCH) {
+      throw new HubError('HUB_COMMAND_BATCH_INVALID', `A command batch holds 1 to ${PULSE_MAX_BATCH} commands`);
+    }
+    return this.lane.background(() => this.#request(`${CONNECTOR_API_BASE}/commands`, payload, {
+      retry: true,
+      maxBodyBytes: PULSE_BODY_BYTES,
+      timeoutMs: MIRROR_TIMEOUT_MS,
+      gzipAboveBytes: MIRROR_GZIP_ABOVE_BYTES,
+    }));
+  }
+
+  /**
+   * One page of this machine's Pulse log after `since` (design §5.4), held up to `wait` seconds when nothing is new:
+   * `{ events, next, head, floor, presence, presenceNext }`. `presence` is the last answer's `presenceNext`, an opaque
+   * keyset, so beats already sent never come back and a held wait holds. Behind the retention floor the cloud answers 410.
+   */
+  sync({ since, wait = 20, presence = null } = {}) {
+    const query = new URLSearchParams({ since: String(since), wait: String(wait), ...(presence ? { presence } : {}) });
+    return this.#request(`${CONNECTOR_API_BASE}/sync?${query}`, undefined, {
+      retry: true, maxBodyBytes: 0, method: 'GET', timeoutMs: (Number(wait) + 10) * 1000,
+    });
+  }
+
+  /** Whether this team has Pulse cloud-first turned on: `{ enabled, since }`. */
+  cloudFirst() {
+    return this.#request(`${CONNECTOR_API_BASE}/cloud-first`, undefined, { retry: true, maxBodyBytes: 0, method: 'GET' });
+  }
+
+  /** The parity report of this machine's mirror against the Pulse log, for the last `hours`; `view: 'reconcile'` asks for
+   * the import reconciliation view of this machine's log instead (ADR-4). */
+  parity({ hours = 6, view = null } = {}) {
+    const query = new URLSearchParams(view ? { view } : { hours: String(hours) });
+    return this.#request(`${CONNECTOR_API_BASE}/parity?${query}`, undefined, { retry: true, maxBodyBytes: 0, method: 'GET', timeoutMs: MIRROR_TIMEOUT_MS });
+  }
+
   /** The heartbeat, session, renew, ack and events calls in flight at any time since `since`, for a pass record. */
   priorityCalls({ since } = {}) {
     return this.lane.calls({ since });

package/src/lib/transportContract.js

@@ -17,6 +17,9 @@ export const CONNECTOR_SCOPES = Object.freeze([
   'agent-hub:connector:renew',
   'agent-hub:connector:event',
   'agent-hub:connector:mirror',
+  // The Pulse log (cloud-first Phase 2): the shadow feed writes commands and reads the cloud-first flag and parity.
+  'agent-hub:connector:sync',
+  'agent-hub:connector:commands',
 ]);
 
 export const CONNECTOR_AUTH_CONTRACT = Object.freeze({