@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

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/secretStore.js

@@ -0,0 +1,169 @@
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import { HubError } from './errors.js';
+import { spawnBounded } from './subprocess.js';
+
+const SERVICE = 'com.agentpulse.hub';
+/** A Keychain or libsecret call normally takes well under a second; one that hangs (a locked keychain) is killed. */
+export const SECRET_COMMAND_TIMEOUT_MS = 10_000;
+
+/** What a secret-command error may carry: the command's output can be a secret, so only how it ended. */
+const exitOnly = ({ code, signal }) => ({ code, signal });
+
+export async function runSecretCommand(bin, args, { input = '', env = process.env, timeoutMs = SECRET_COMMAND_TIMEOUT_MS } = {}) {
+  let result;
+  try {
+    result = await spawnBounded(bin, args, {
+      input,
+      env,
+      timeoutMs,
+      onTimeout: () => new HubError('HUB_SECRET_STORE_TIMEOUT', `${bin} did not answer within ${timeoutMs} ms and was stopped`),
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new HubError(
+        'HUB_SECRET_STORE_UNAVAILABLE',
+        `${bin} is not installed; Pulse stores sign-in and keys only in the OS keychain (install libsecret's secret-tool on Linux)`,
+        { cause: error },
+      );
+    }
+    if (error.result) error.result = exitOnly(error.result);
+    throw error;
+  }
+  if (result.code === 0) return result;
+  const error = new HubError('HUB_SECRET_STORE_FAILED', `${bin} failed with exit ${result.code}`);
+  error.result = exitOnly(result);
+  throw error;
+}
+
+const SECURITY = '/usr/bin/security';
+const CHUNKED_PREFIX = 'b64chunks:';
+const CHUNK_CHARACTERS = 1024;
+const KEYCHAIN_NAME = /^[A-Za-z0-9._@-]+$/;
+
+export class KeychainSecretStore {
+  constructor({ execute = runSecretCommand, account = os.userInfo().username } = {}) {
+    if (!KEYCHAIN_NAME.test(account)) {
+      throw new HubError('HUB_SECRET_STORE_UNAVAILABLE', 'The macOS account name cannot be used as a Keychain account');
+    }
+    this.execute = execute;
+    this.account = account;
+  }
+
+  #service(reference) {
+    const service = `${SERVICE}.${reference}`;
+    if (!KEYCHAIN_NAME.test(service)) throw new HubError('HUB_SECRET_STORE_FAILED', 'Invalid Keychain item name');
+    return service;
+  }
+
+  async #find(service) {
+    try {
+      const result = await this.execute(SECURITY, ['find-generic-password', '-a', this.account, '-s', service, '-w']);
+      return result.stdout.replace(/\n$/, '');
+    } catch (error) {
+      if (error.result?.code === 44) return null;
+      throw error;
+    }
+  }
+
+  async #remove(service) {
+    try {
+      await this.execute(SECURITY, ['delete-generic-password', '-a', this.account, '-s', service]);
+    } catch (error) {
+      if (error.result?.code !== 44) throw error;
+    }
+  }
+
+  async #write(entries) {
+    const lines = entries.map(([service, data]) => `add-generic-password -U -a "${this.account}" -s "${service}" -w ${data}`);
+    await this.execute(SECURITY, ['-i'], { input: `${lines.join('\n')}\n` });
+  }
+
+  static #parts(service, header) {
+    if (!header?.startsWith(CHUNKED_PREFIX)) return null;
+    const [generation, count] = header.slice(CHUNKED_PREFIX.length).split(':');
+    return Array.from({ length: Number(count) || 0 }, (_unused, index) => `${service}.${generation}.${index}`);
+  }
+
+  async get(reference) {
+    const service = this.#service(reference);
+    const header = await this.#find(service);
+    const parts = KeychainSecretStore.#parts(service, header);
+    if (!parts) return header;
+    const chunks = [];
+    for (const part of parts) {
+      const chunk = await this.#find(part);
+      if (chunk === null) throw new HubError('HUB_SECRET_STORE_CORRUPT', 'A Keychain secret is incomplete');
+      chunks.push(chunk);
+    }
+    return Buffer.from(chunks.join(''), 'base64').toString('utf8');
+  }
+
+  async set(reference, value) {
+    const service = this.#service(reference);
+    const previous = KeychainSecretStore.#parts(service, await this.#find(service)) || [];
+    const encoded = Buffer.from(String(value), 'utf8').toString('base64');
+    const chunks = encoded.match(new RegExp(`.{1,${CHUNK_CHARACTERS}}`, 'g')) || [];
+    const generation = randomBytes(6).toString('hex');
+    if (chunks.length) {
+      await this.#write(chunks.map((chunk, index) => [`${service}.${generation}.${index}`, chunk]));
+    }
+    await this.#write([[service, `${CHUNKED_PREFIX}${generation}:${chunks.length}`]]);
+    if ((await this.get(reference)) !== String(value)) {
+      throw new HubError('HUB_SECRET_STORE_FAILED', 'The Keychain did not store the secret intact');
+    }
+    for (const part of previous) await this.#remove(part);
+  }
+
+  async delete(reference) {
+    const service = this.#service(reference);
+    const parts = KeychainSecretStore.#parts(service, await this.#find(service)) || [];
+    await this.#remove(service);
+    for (const part of parts) await this.#remove(part);
+  }
+}
+
+export class LibsecretStore {
+  constructor({ execute = runSecretCommand } = {}) {
+    this.execute = execute;
+  }
+
+  async get(reference) {
+    try {
+      const result = await this.execute('secret-tool', [
+        'lookup',
+        'service',
+        SERVICE,
+        'reference',
+        reference,
+      ]);
+      return result.stdout.replace(/\n$/, '');
+    } catch (error) {
+      if (error.result?.code === 1) return null;
+      throw error;
+    }
+  }
+
+  async set(reference, value) {
+    await this.execute(
+      'secret-tool',
+      ['store', '--label', 'AgentPulse Pulse connector', 'service', SERVICE, 'reference', reference],
+      { input: String(value) }
+    );
+  }
+
+  async delete(reference) {
+    await this.execute('secret-tool', ['clear', 'service', SERVICE, 'reference', reference]);
+  }
+}
+
+export function defaultSecretStore(platform = process.platform) {
+  switch (platform) {
+    case 'darwin':
+      return new KeychainSecretStore();
+    case 'linux':
+      return new LibsecretStore();
+    default:
+      throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Pulse supports macOS and Linux, not ${platform}`);
+  }
+}