@agentpulselabs/cli-plugin-pulse 0.2.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/storage.js

@@ -0,0 +1,131 @@
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { HubError } from './errors.js';
+
+export async function ensureOwnerOnlyDirectory(directory) {
+  const absolute = path.resolve(directory);
+  const root = path.parse(absolute).root;
+  const components = absolute.slice(root.length).split(path.sep).filter(Boolean);
+  let current = root;
+  let ownerAnchorReached = false;
+  for (const component of components) {
+    current = path.join(current, component);
+    try {
+      const componentInfo = await lstat(current);
+      if (componentInfo.isSymbolicLink()) {
+        if (ownerAnchorReached || current === absolute) {
+          throw new HubError('HUB_UNSAFE_STORAGE', `Storage ancestor is a symlink: ${current}`);
+        }
+        continue;
+      }
+      if (!componentInfo.isDirectory()) {
+        throw new HubError('HUB_UNSAFE_STORAGE', `Storage ancestor is not a directory: ${current}`);
+      }
+      if (typeof process.getuid === 'function' && componentInfo.uid === process.getuid()) {
+        ownerAnchorReached = true;
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await mkdir(current, { mode: 0o700 });
+      ownerAnchorReached = true;
+    }
+  }
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new HubError('HUB_UNSAFE_STORAGE', `Storage path is not a real directory: ${directory}`);
+  }
+  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) {
+    throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage path is not owned by the current user: ${directory}`);
+  }
+  await chmod(directory, 0o700);
+  return directory;
+}
+
+export async function assertOwnerOnlyFile(file) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new HubError('HUB_UNSAFE_STORAGE', `Storage path is not a regular file: ${file}`);
+  }
+  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) {
+    throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage file is not owned by the current user: ${file}`);
+  }
+  if ((info.mode & 0o077) !== 0) {
+    throw new HubError('HUB_STORAGE_PERMISSIONS', `Storage file must be owner-only: ${file}`);
+  }
+}
+
+export async function writeOwnerOnlyJson(file, value) {
+  return writeOwnerOnlyText(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function writeOwnerOnlyText(file, value) {
+  const directory = path.dirname(file);
+  await ensureOwnerOnlyDirectory(directory);
+  try {
+    const existing = await lstat(file);
+    if (existing.isSymbolicLink()) {
+      throw new HubError('HUB_UNSAFE_STORAGE', `Refusing to replace symlink: ${file}`);
+    }
+    if (!existing.isFile()) {
+      throw new HubError('HUB_UNSAFE_STORAGE', `Refusing to replace non-file storage: ${file}`);
+    }
+    if (typeof process.getuid === 'function' && existing.uid !== process.getuid()) {
+      throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage file is not owned by the current user: ${file}`);
+    }
+    if ((existing.mode & 0o077) !== 0) {
+      throw new HubError('HUB_STORAGE_PERMISSIONS', `Storage file must already be owner-only: ${file}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = path.join(
+    directory,
+    `.${path.basename(file)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
+  );
+  const handle = await open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(String(value), 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+    try {
+      const directoryHandle = await open(directory, 'r');
+      try {
+        await directoryHandle.sync();
+      } finally {
+        await directoryHandle.close();
+      }
+    } catch {
+      // Some filesystems do not support directory fsync; the atomic rename still applies.
+    }
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function readOwnerOnlyJson(file, fallback = null) {
+  try {
+    await assertOwnerOnlyFile(file);
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    if (error instanceof SyntaxError) {
+      throw new HubError('HUB_INVALID_CONFIG', `Invalid JSON in ${file}`, { cause: error });
+    }
+    throw error;
+  }
+}

package/src/lib/subprocess.js

@@ -0,0 +1,45 @@
+import { execFile as execFileCallback, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const SUBPROCESS_TIMEOUT_MS = 30_000;
+
+const execFileAsync = promisify(execFileCallback);
+const bounded = (ms, fallback) => (Number.isFinite(ms) && ms > 0 ? ms : fallback);
+
+/** execFile that always ends: past its timeout (never unbounded, not even with timeout: 0) the child is SIGKILLed. */
+export function execFileBounded(bin, args, { defaultTimeoutMs = SUBPROCESS_TIMEOUT_MS, ...options } = {}) {
+  return execFileAsync(bin, args, { ...options, timeout: bounded(options.timeout, defaultTimeoutMs), killSignal: 'SIGKILL' });
+}
+
+/**
+ * Runs bin with input on stdin and resolves { code, signal, stdout, stderr } when it exits. Past timeoutMs the child
+ * is SIGKILLed and the promise rejects with onTimeout(result), so a hung tool never holds its caller.
+ */
+export function spawnBounded(bin, args, {
+  input = '', env = process.env, timeoutMs = SUBPROCESS_TIMEOUT_MS, onTimeout = () => Object.assign(new Error(`${bin} timed out`), { code: 'ETIMEDOUT' }),
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    const stdout = [];
+    const stderr = [];
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, bounded(timeoutMs, SUBPROCESS_TIMEOUT_MS));
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const result = { code, signal, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') };
+      if (timedOut) reject(Object.assign(onTimeout(result), { result }));
+      else resolve(result);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}