@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/application.js

@@ -0,0 +1,656 @@
+import { spawn } from 'node:child_process';
+import { lstat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { readCliDefaults } from './cliDefaults.js';
+import { CloudAuth } from './cloudAuth.js';
+import { createClaudeDriver, createCursorDriver } from './drivers.js';
+import { HubError } from './errors.js';
+import { fetchJson } from './http.js';
+import { loadIdentity, loadOrCreateIdentity } from './identity.js';
+import { MIRROR_SCOPE } from './mirrorContract.js';
+import { localScopeCheckApplies, MIRROR_STATE_FILE, mirrorEnabled } from './mirrorDaemon.js';
+import { MirrorSync, requestResend } from './mirrorSync.js';
+import { loginWithBrowser } from './oauthLogin.js';
+import { assertPairedConfig, pairedStatus } from './pairedConfig.js';
+import { pairConnector } from './pairingLifecycle.js';
+import { ProcessSupervisor } from './processSupervisor.js';
+import { defaultSecretStore } from './secretStore.js';
+import { consumeRestartRequest, RESTART_REQUEST_FILE } from './selfRestart.js';
+import { ServiceManager } from './serviceManager.js';
+import {
+  ensureOwnerOnlyDirectory,
+  readOwnerOnlyJson,
+  writeOwnerOnlyJson,
+} from './storage.js';
+import { TokenStore } from './tokenStore.js';
+import { USER_API_BASE } from './transportContract.js';
+
+const CONFIG_FILE = 'config.json';
+const HUB_WRITE = 'hub.write';
+// The daemon publishes its first heartbeat after its first cloud cycle, which includes a reconnect and a claim poll.
+const START_HEALTH_POLL_MS = 250;
+const RESTART_POLL_MS = 500;
+const DAEMON_PATH = fileURLToPath(new URL('../daemon/main.js', import.meta.url));
+const SIGN_IN_HINT = 'Run `agentpulse pulse login`, then `agentpulse pulse start`.';
+const STALE_SERVICE_MESSAGE = 'The Pulse connector service points at an old daemon path.';
+const RECONCILE_STALE_MS = 5 * 60_000;
+const DEFAULT_PAIRING_POLICY = Object.freeze({
+  capabilities: Object.freeze(['workspace.read', 'git.read']),
+  providerPolicy: Object.freeze({
+    providers: Object.freeze({}),
+    maxConcurrency: 1,
+    maxTokensPerRun: 1,
+    maxCostUsd: 0,
+  }),
+});
+
+export function defaultConfigDirectory(home = os.homedir()) {
+  return path.join(
+    process.env.XDG_CONFIG_HOME || path.join(home, '.config'),
+    'agentpulse',
+    'hub'
+  );
+}
+
+function baseConfig(identity) {
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    installedAt: new Date().toISOString(),
+    identityFingerprint: identity.fingerprint,
+    paired: null,
+  };
+}
+
+async function openInBrowser(url) {
+  const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+  spawn(opener, [url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+}
+
+const BUSY_STATES = new Set(['running', 'idle_unpaired', 'starting']);
+
+/** What the daemon's last heartbeat says beyond "running": not taking work, jobs being recovered, settlements given up. */
+function healthSummary(health) {
+  if (!health) return '';
+  let summary = '';
+  if (health.state && !BUSY_STATES.has(health.state)) {
+    summary += ` It is not taking work: ${health.state}${health.code ? ` (${health.code})` : ''}.`;
+    if (health.message) summary += ` ${health.message}`;
+  } else if (health.state === 'starting') {
+    summary += ' It is still connecting to the cloud.';
+  }
+  const loop = health.degraded?.code === 'restart_loop' ? health.degraded : null;
+  if (loop) {
+    summary += ` It restarted ${loop.restarts} times in 5 minutes, so it holds further restarts until ${loop.clearsAt} (restart_loop)`;
+    summary += loop.pending ? `; a ${loop.pending} restart is waiting.` : '.';
+  }
+  for (const job of health.recovering || []) {
+    summary += ` Recovering job ${job.jobId} (${job.code}, ${job.failures} failed ${job.failures === 1 ? 'try' : 'tries'}).`;
+  }
+  for (const job of health.settleFailed || []) {
+    summary += ` Gave up settling job ${job.jobId} (${job.code}); the cloud will expire it as connector_no_result.`;
+  }
+  return summary;
+}
+
+export class ConnectorApplication {
+  constructor({
+    configDir = defaultConfigDirectory(),
+    secretStore = defaultSecretStore(),
+    serviceManager = new ServiceManager({ daemonPath: DAEMON_PATH, configDir }),
+    pairingPolicy = DEFAULT_PAIRING_POLICY,
+    providerProbes = null,
+    fetch = globalThis.fetch,
+    login = null,
+    cliDefaults = readCliDefaults,
+    now = Date.now,
+    log = (line) => process.stderr.write(`${line}\n`),
+    startHealthTimeoutMs = 10_000,
+    restartTimeoutMs = 60_000,
+  } = {}) {
+    this.startHealthTimeoutMs = startHealthTimeoutMs;
+    this.restartTimeoutMs = restartTimeoutMs;
+    this.configDir = configDir;
+    this.secretStore = secretStore;
+    this.serviceManager = serviceManager;
+    this.pairingPolicy = structuredClone(pairingPolicy);
+    this.providerProbes = providerProbes || this.#defaultProviderProbes.bind(this);
+    this.fetch = fetch;
+    this.browserLogin = login || ((options) => loginWithBrowser({
+      ...options,
+      fetch,
+      now,
+      openBrowser: openInBrowser,
+      onAuthUrl: (url) => log(`Opening your browser to sign in. If it does not open, visit:\n  ${url}`),
+    }));
+    this.cliDefaults = cliDefaults;
+    this.now = now;
+    this.tokenStore = new TokenStore({ secretStore, configDir });
+    this.configFile = path.join(configDir, CONFIG_FILE);
+  }
+
+  async #defaultProviderProbes() {
+    const supervisor = new ProcessSupervisor();
+    const cursor = createCursorDriver({ supervisor });
+    const claude = createClaudeDriver({ supervisor });
+    const [cursorStatus, claudeStatus] = await Promise.all([cursor.probe(), claude.probe()]);
+    return { cursor: cursorStatus, claude: claudeStatus };
+  }
+
+  async #config(required = true) {
+    const config = await readOwnerOnlyJson(this.configFile);
+    if (!config && required) {
+      throw new HubError('HUB_NOT_INSTALLED', 'Pulse connector is not installed. Run agentpulse pulse install.');
+    }
+    return config;
+  }
+
+  async #authStatus() {
+    try {
+      const session = await this.tokenStore.load();
+      if (!session) return { ok: false, code: 'HUB_LOGIN_REQUIRED', hint: SIGN_IN_HINT };
+      const expired = Date.parse(session.expiresAt || '') <= this.now();
+      return {
+        ok: !expired || Boolean(session.refreshToken),
+        userId: session.userId,
+        expiresAt: session.expiresAt,
+        ...(expired ? { code: 'HUB_ACCESS_TOKEN_EXPIRED', hint: SIGN_IN_HINT } : {}),
+      };
+    } catch (error) {
+      return { ok: false, code: error.code || 'HUB_TOKEN_STORE_FAILED', hint: SIGN_IN_HINT };
+    }
+  }
+
+  async #servicePath() {
+    if (typeof this.serviceManager.daemonPathCheck !== 'function') return { ok: true };
+    return this.serviceManager.daemonPathCheck();
+  }
+
+  async install() {
+    await ensureOwnerOnlyDirectory(this.configDir);
+    const identity = await loadOrCreateIdentity({
+      secretStore: this.secretStore,
+      configDir: this.configDir,
+    });
+    const existing = await this.#config(false);
+    if (existing && existing.identityFingerprint !== identity.fingerprint) {
+      throw new HubError(
+        'HUB_IDENTITY_MISMATCH',
+        'Stored connector configuration does not match the local device identity'
+      );
+    }
+    await writeOwnerOnlyJson(this.configFile, existing || baseConfig(identity));
+    const service = await this.serviceManager.install();
+    return {
+      command: 'install',
+      state: 'installed',
+      serviceFile: service.serviceFile,
+      identityFingerprint: identity.fingerprint,
+      message: existing && pairedStatus(existing).ok
+        ? 'Pulse connector installed. This machine is already paired; run `agentpulse pulse start`.'
+        : 'Pulse connector installed. Pair this machine before starting the daemon.',
+    };
+  }
+
+  async pair({ org, platformUrl, displayName = os.hostname(), roots = [] } = {}) {
+    const config = await this.#config();
+    return pairConnector({
+      config,
+      configDir: this.configDir,
+      configFile: this.configFile,
+      tokenStore: this.tokenStore,
+      fetch: this.fetch,
+      login: this.browserLogin,
+      cliDefaults: this.cliDefaults,
+      now: this.now,
+      pairingPolicy: this.pairingPolicy,
+      platformUrl,
+      org,
+      displayName,
+      roots,
+    });
+  }
+
+  async login({ platformUrl } = {}) {
+    const config = await this.#config();
+    const paired = config.paired ? assertPairedConfig(config) : null;
+    const target = platformUrl || paired?.target.platformUrl || (await this.cliDefaults()).platformUrl;
+    if (!target) throw new HubError('HUB_PLATFORM_REQUIRED', 'Pass --platform <url> or run `agentpulse login` first');
+    const session = await this.browserLogin({ platformUrl: target });
+    if (paired && (session.userId !== paired.userId || session.teamId !== paired.teamId)) {
+      throw new HubError(
+        'HUB_LOGIN_IDENTITY_MISMATCH',
+        'This machine was paired by a different user or team; sign in as that user or revoke and pair again',
+      );
+    }
+    await this.tokenStore.save(session);
+    return {
+      command: 'login',
+      state: 'signed_in',
+      expiresAt: session.expiresAt,
+      message: paired ? 'Signed in. Run `agentpulse pulse start` to resume the connector.' : 'Signed in.',
+    };
+  }
+
+  async start() {
+    const config = await this.#config();
+    const servicePath = await this.#servicePath();
+    if (!servicePath.ok) throw new HubError(servicePath.code, `${STALE_SERVICE_MESSAGE} ${servicePath.hint}`);
+    assertPairedConfig(config);
+    const auth = await this.#authStatus();
+    if (!auth.ok) throw new HubError('HUB_LOGIN_REQUIRED', `Pulse connector is not signed in. ${SIGN_IN_HINT}`);
+    const requestedAt = Date.now();
+    const service = await this.serviceManager.start();
+    let daemonState = null;
+    if (typeof this.serviceManager.health === 'function') {
+      let health = await this.serviceManager.health({ after: requestedAt });
+      while (!health.ok && Date.now() - requestedAt < this.startHealthTimeoutMs) {
+        await delay(START_HEALTH_POLL_MS);
+        health = await this.serviceManager.health({ after: requestedAt });
+      }
+      const reported = health?.health;
+      if (health?.ok && ['error', 'failed'].includes(reported?.state)) {
+        throw new HubError('HUB_DAEMON_UNHEALTHY', `Pulse daemon reported ${reported.code || reported.state}; see \`agentpulse pulse doctor\``);
+      }
+      if (health?.ok) {
+        daemonState = reported?.state || null;
+      } else if ((await this.serviceManager.status()).state === 'running') {
+        // No heartbeat since the start request, so the daemon is still booting into its first sync.
+        daemonState = 'first_sync';
+      } else {
+        throw new HubError('HUB_DAEMON_UNHEALTHY', 'Pulse daemon did not start within 10 seconds; see `agentpulse pulse doctor`');
+      }
+    }
+    let message = service.state === 'running' ? 'Pulse connector started.' : 'Pulse connector start requested.';
+    if (daemonState === 'starting') {
+      message = 'Pulse connector started and is connecting to the cloud; `agentpulse pulse status` shows when it is online.';
+    }
+    if (daemonState === 'first_sync') {
+      message = 'Pulse connector is starting; its first sync is still in progress. `agentpulse pulse status` shows when it is online.';
+    }
+    return {
+      command: 'start',
+      ...service,
+      ...(daemonState ? { daemonState } : {}),
+      message,
+    };
+  }
+
+  /**
+   * Asks the running daemon to restart itself by writing restart.request, then waits for a fresh heartbeat from a new
+   * pid. It never calls launchctl or systemctl, so a sandboxed caller can restart the daemon without approval.
+   */
+  async restart() {
+    await this.#config();
+    const healthFile = path.join(this.configDir, 'daemon-health.json');
+    const current = await this.serviceManager.health();
+    const before = current.health;
+    if (!current.ok) {
+      throw new HubError(
+        'HUB_DAEMON_NOT_RUNNING',
+        before?.heartbeatAt
+          ? `Pulse daemon has not sent a heartbeat since ${before.heartbeatAt}, so it is not running or is stuck; nothing can restart it from here. Run \`agentpulse pulse start\`.`
+          : 'Pulse daemon has never sent a heartbeat, so it is not running. Run `agentpulse pulse start`.',
+      );
+    }
+    const requestedAt = Date.now();
+    await writeOwnerOnlyJson(path.join(this.configDir, RESTART_REQUEST_FILE), {
+      requestedAt: new Date(requestedAt).toISOString(),
+      pid: process.pid,
+    });
+    const deferred = (loop) => new HubError(
+      'HUB_RESTART_DEFERRED',
+      `Pulse restart deferred until ${loop.clearsAt}: the daemon restarted ${loop.restarts} times in 5 minutes. The request stays queued until then.`,
+    );
+    if (before?.degraded?.code === 'restart_loop') throw deferred(before.degraded);
+    for (;;) {
+      const { ok, health } = await this.serviceManager.health({ after: requestedAt });
+      if (ok && health.pid !== before?.pid) {
+        return {
+          command: 'restart',
+          state: 'restarted',
+          pid: health.pid,
+          previousPid: before?.pid ?? null,
+          daemonState: health.state,
+          message: `Pulse connector restarted (pid ${before?.pid ?? 'none'} → ${health.pid}).`,
+        };
+      }
+      if (Date.now() - requestedAt >= this.restartTimeoutMs) break;
+      await delay(RESTART_POLL_MS);
+    }
+    const latest = await readOwnerOnlyJson(healthFile).catch(() => null);
+    if (latest?.degraded?.code === 'restart_loop') throw deferred(latest.degraded);
+    // The daemon took the request and is letting running jobs finish; the restart is under way, not lost.
+    if (latest?.restarting && latest.pid === before?.pid) {
+      const jobs = latest.restarting.draining || [];
+      return {
+        command: 'restart',
+        state: 'draining',
+        pid: latest.pid,
+        draining: jobs,
+        message: `Pulse restarts once ${jobs.length ? `job${jobs.length === 1 ? '' : 's'} ${jobs.join(', ')} finish${jobs.length === 1 ? 'es' : ''}` : 'its current cycle ends'}; \`agentpulse pulse status\` shows the new process when it is up.`,
+      };
+    }
+    await consumeRestartRequest(this.configDir).catch(() => {});
+    throw new HubError(
+      'HUB_RESTART_TIMEOUT',
+      `Pulse daemon did not restart within ${Math.round(this.restartTimeoutMs / 1000)} seconds; it may not be running. See \`agentpulse pulse status\`.`,
+    );
+  }
+
+  async status() {
+    const config = await this.#config();
+    const service = await this.serviceManager.status();
+    const health = await readOwnerOnlyJson(path.join(this.configDir, 'daemon-health.json'));
+    const pairing = pairedStatus(config);
+    const auth = await this.#authStatus();
+    const servicePath = await this.#servicePath();
+    const needsSignIn = !auth.ok || health?.state === 'auth_required';
+    let message = `Pulse connector is ${service.state}${pairing.ok ? '' : ' and unpaired'}.`;
+    if (needsSignIn) message = `Pulse connector is ${service.state} and needs you to sign in again. ${SIGN_IN_HINT}`;
+    if (!servicePath.ok) message = `${STALE_SERVICE_MESSAGE} ${servicePath.hint}`;
+    if (!needsSignIn && servicePath.ok && service.state === 'running') message += healthSummary(health);
+    const jobError = health?.lastJobError;
+    if (jobError?.code) {
+      message += ` Last job error: ${jobError.code} on ${jobError.type || 'a job'}${jobError.at ? ` at ${jobError.at}` : ''} (job ${jobError.jobId}).`;
+    }
+    return {
+      command: 'status',
+      state: service.state,
+      pid: service.pid,
+      paired: pairing.ok,
+      machineId: pairing.ok ? pairing.machineId : null,
+      pairing,
+      auth,
+      servicePath,
+      health,
+      message,
+    };
+  }
+
+  async doctor() {
+    const checks = {};
+    const config = await this.#config(false);
+    try {
+      const directory = await lstat(this.configDir);
+      const configInfo = await lstat(this.configFile);
+      checks.storage = {
+        ok:
+          directory.isDirectory() &&
+          (directory.mode & 0o077) === 0 &&
+          configInfo.isFile() &&
+          (configInfo.mode & 0o077) === 0,
+      };
+    } catch (error) {
+      checks.storage = { ok: false, code: error.code };
+    }
+    try {
+      const identity = await loadIdentity({ secretStore: this.secretStore, configDir: this.configDir });
+      checks.identity = { ok: true, fingerprint: identity.fingerprint };
+    } catch (error) {
+      checks.identity = { ok: false, code: error.code || 'HUB_IDENTITY_FAILED' };
+    }
+    const service = await this.serviceManager.status();
+    checks.service = { ok: ['running', 'loaded', 'stopped', 'inactive'].includes(service.state), ...service };
+    checks.servicePath = await this.#servicePath();
+    checks.providers = await this.providerProbes();
+    checks.pairing = pairedStatus(config);
+    checks.auth = config ? await this.#authStatus() : { ok: false, code: 'HUB_NOT_INSTALLED' };
+    const ok =
+      checks.storage.ok &&
+      checks.identity.ok &&
+      checks.service.ok &&
+      checks.servicePath.ok &&
+      checks.pairing.ok &&
+      checks.auth.ok;
+    return {
+      command: 'doctor',
+      state: ok ? 'healthy' : 'unhealthy',
+      ok,
+      checks,
+      message: ok
+        ? 'Pulse local installation, pairing and sign-in are healthy.'
+        : 'Pulse local installation has failed checks.',
+    };
+  }
+
+  async mirror({ action }) {
+    const config = await this.#config();
+    const scopeGranted = localScopeCheckApplies(config)
+      ? (await this.tokenStore.scopes()).includes(MIRROR_SCOPE)
+      : null;
+    const loginHint = scopeGranted === false ? ' Your sign-in predates the mirror scope; run `agentpulse pulse login`.' : '';
+    switch (action) {
+      case 'on':
+      case 'off': {
+        const localHub = action === 'on';
+        await writeOwnerOnlyJson(this.configFile, { ...config, mirror: { ...config.mirror, localHub } });
+        return {
+          command: 'mirror',
+          enabled: localHub,
+          scopeGranted,
+          message: localHub
+            ? `Local Agent Hub mirroring is on; the daemon picks it up within a heartbeat.${loginHint}`
+            : 'Local Agent Hub mirroring is off. Items already mirrored stay in Pulse until they change or you remove them there.',
+        };
+      }
+      case 'status': {
+        const state = await new MirrorSync({ stateFile: path.join(this.configDir, MIRROR_STATE_FILE) }).status();
+        const enabled = mirrorEnabled(config);
+        const mirroredTotal = Object.values(state.mirrored).reduce((sum, count) => sum + count, 0);
+        let message = `Local Agent Hub mirroring is ${enabled ? 'on' : 'off'}.`;
+        if (enabled && !pairedStatus(config).ok) message += ' This machine is not paired.';
+        if (enabled) message += loginHint;
+        if (state.lastSyncAt) message += ` Last sync ${new Date(state.lastSyncAt).toISOString()}; ${mirroredTotal} items mirrored.`;
+        if (state.lastPass) {
+          const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+          const kilobytes = (bytes) => `${Math.round(bytes / 1024)} KB`;
+          const short = (value) => (value < 1000 ? `${Math.round(value)} ms` : seconds(value));
+          const { ms, collectMs, uploadMs, batches, bytes, sentBytes, slowestBatch } = state.lastPass;
+          const sent = Number.isFinite(sentBytes) && batches > 0 ? `, ${kilobytes(sentBytes)} sent for ${kilobytes(bytes)} of JSON` : '';
+          message += ` The last pass took ${seconds(ms)}`;
+          message += Number.isFinite(collectMs) ? ` (reading the hub ${seconds(collectMs)}, uploading ${batches} batch${batches === 1 ? '' : 'es'} ${seconds(uploadMs)}${sent}).` : '.';
+          if (slowestBatch) {
+            const parts = [];
+            if (slowestBatch.backoffMs > 0) parts.push(`${seconds(slowestBatch.backoffMs)} backing off (responses ${slowestBatch.statuses.join(', ')})`);
+            if (slowestBatch.laneWaitMs > 0) {
+              const held = (slowestBatch.heldBy || []).map((call) =>
+                `${call.path}, ${call.attempts} attempt${call.attempts === 1 ? '' : 's'}, ${call.done ? `${short(call.ms)}` : 'still running'}`);
+              const detail = [...held, ...(slowestBatch.laneCapped ? ['then sent alongside'] : [])].join('; ');
+              parts.push(`${seconds(slowestBatch.laneWaitMs)} behind priority calls${detail ? ` (${detail})` : ''}`);
+            }
+            if (slowestBatch.credentialsMs > 0) parts.push(`${seconds(slowestBatch.credentialsMs)} reading credentials`);
+            if (slowestBatch.serverMs !== null) {
+              parts.push(`${short(slowestBatch.serverMs)} on the server${slowestBatch.dbMs !== null ? ` (${short(slowestBatch.dbMs)} in the database)` : ''}`);
+            }
+            parts.push(`${seconds(slowestBatch.networkMs)} on the network${slowestBatch.serverMs === null ? ' and the server' : ''}`);
+            message += ` Its slowest batch, ${slowestBatch.items} items in ${seconds(slowestBatch.ms)}: ${parts.join(', ')}.`;
+          }
+        }
+        const dropped = Object.entries(state.dropped).flatMap(([kind, reasons]) =>
+          Object.entries(reasons).map(([reason, count]) => `${count} ${kind} (${reason})`));
+        if (dropped.length) message += ` Not mirrored: ${dropped.join(', ')}.`;
+        if (state.redactedTotal > 0) {
+          const last = state.redactedLastAt ? ` (the last at ${new Date(state.redactedLastAt).toISOString()})` : '';
+          message += ` Pulse redacted ${state.redactedTotal} secret${state.redactedTotal === 1 ? '' : 's'} from this machine's uploads${last}; check what this connector sends.`;
+        }
+        if (state.rejected) message += ` Pulse refused ${state.rejected} item${state.rejected === 1 ? '' : 's'}; \`agentpulse pulse mirror resend-rejected\` sends refused items again.`;
+        const graphRows = Object.entries(state.graphDropped || {}).flatMap(([window, sections]) => Object.entries(sections).flatMap(([section, reasons]) =>
+          Object.entries(reasons).map(([reason, count]) => `${count} ${section} in the ${window} window (${reason})`)));
+        if (graphRows.length) message += ` Graph rows not mirrored: ${graphRows.join(', ')}.`;
+        const absent = Object.entries(state.lastAbsent || {}).map(([read, count]) => `${count} ${read}`);
+        if (absent.length) message += ` Absent on the local hub at the last reconcile (not an error): ${absent.join(', ')}.`;
+        if (state.lastError) message += ` Last blocking error: ${state.lastError.code}.`;
+        const reconcileStale = enabled && Boolean(state.lastSyncAt) && (!state.lastCompleteAt || Date.now() - state.lastCompleteAt > RECONCILE_STALE_MS);
+        if (state.lastCompleteAt) message += ` Last complete reconcile ${new Date(state.lastCompleteAt).toISOString()}.`;
+        if (reconcileStale) {
+          message += state.lastCompleteAt
+            ? ' Warning: no complete reconcile for over 5 minutes, so local deletions are not reaching Pulse.'
+            : ' Warning: no complete reconcile yet, so local deletions are not reaching Pulse.';
+        }
+        if (state.lastError?.code === 'HUB_MIRROR_SCOPE_MISSING' && scopeGranted !== false) {
+          message += ' Pulse refused mirroring: your seat or plan does not include the mirror scope.';
+        }
+        const blocked = enabled && Boolean(state.lastError?.retryAt);
+        if (blocked) message += ` Mirroring is paused; the daemon retries at ${new Date(state.lastError.retryAt).toISOString()}.`;
+        return {
+          command: 'mirror',
+          enabled,
+          state: enabled ? (blocked ? 'blocked' : 'on') : 'off',
+          code: blocked ? state.lastError.code : null,
+          scopeGranted,
+          reconcileStale,
+          ...state,
+          message,
+        };
+      }
+      case 'resend-rejected': {
+        const { rejected } = await requestResend(this.configDir, { stateFile: path.join(this.configDir, MIRROR_STATE_FILE) });
+        return {
+          command: 'mirror',
+          rejected,
+          message: `${rejected} refused item${rejected === 1 ? ' is' : 's are'} sent again on the daemon's next full pass; each is sent once, and one Pulse refuses again stays listed in \`agentpulse pulse mirror status\`.`,
+        };
+      }
+      default:
+        throw new HubError('HUB_MIRROR_ACTION_INVALID', `Unknown mirror action: ${action}`);
+    }
+  }
+
+  async hubWrite({ action }) {
+    const config = await this.#config();
+    if (!config.paired) {
+      throw new HubError('HUB_NOT_PAIRED', 'This machine is not paired; run `agentpulse pulse pair` first.');
+    }
+    const paired = assertPairedConfig(config);
+    const auth = new CloudAuth({
+      tokenStore: this.tokenStore,
+      fetch: this.fetch,
+      now: this.now,
+      target: {
+        platformUrl: paired.target.platformUrl,
+        devOrg: paired.target.devOrg,
+        instanceUrl: paired.baseUrl,
+        userId: paired.userId,
+        teamId: paired.teamId,
+      },
+    });
+    const machineUrl = `${paired.baseUrl}${USER_API_BASE}/machines/${encodeURIComponent(paired.machineId)}`;
+    const read = await fetchJson({ fetch: this.fetch, method: 'GET', url: machineUrl, headers: await auth.credentials() });
+    if (!read.ok) throw new HubError(read.body.error || `HTTP_${read.status}`, read.body.message || 'Could not read this machine from Pulse');
+    const grant = read.body.machine?.active_grant;
+    if (!grant || grant.state !== 'active' || !Array.isArray(grant.capabilities)) {
+      throw new HubError('HUB_GRANT_MISSING', 'This machine has no active grant in Pulse; pair it again.');
+    }
+    const granted = grant.capabilities.includes(HUB_WRITE);
+    if (action === 'status') {
+      return {
+        command: 'hub-write',
+        enabled: granted,
+        policyVersion: grant.version,
+        message: granted
+          ? 'Pulse may post to the local Agent Hub as you (hub.write is granted).'
+          : 'Pulse cannot post to the local Agent Hub (hub.write is off). Turn it on with `agentpulse pulse hub-write on`.',
+      };
+    }
+    if (action !== 'on' && action !== 'off') {
+      throw new HubError('HUB_WRITE_ACTION_INVALID', `Unknown hub-write action: ${action}`);
+    }
+    const enable = action === 'on';
+    if (enable === granted) {
+      return {
+        command: 'hub-write',
+        enabled: granted,
+        policyVersion: grant.version,
+        changed: false,
+        message: `hub.write is already ${granted ? 'on' : 'off'}.`,
+      };
+    }
+    const capabilities = enable
+      ? [...grant.capabilities, HUB_WRITE]
+      : grant.capabilities.filter((capability) => capability !== HUB_WRITE);
+    const replaced = await fetchJson({
+      fetch: this.fetch,
+      method: 'PUT',
+      url: `${machineUrl}/grant`,
+      headers: await auth.credentials(),
+      body: {
+        roots: grant.roots.map(({ rootId, label, canonicalPathHash, displayPath, repoWrite }) =>
+          ({ rootId, label, canonicalPathHash, displayPath, repoWrite })),
+        capabilities,
+        providerPolicy: grant.providerPolicy,
+      },
+    });
+    if (!replaced.ok) {
+      throw new HubError(replaced.body.error || `HTTP_${replaced.status}`, replaced.body.message || 'Pulse refused the grant change');
+    }
+    const version = Number(replaced.body.grant?.version);
+    if (!Number.isInteger(version)) throw new HubError('HUB_GRANT_INVALID', 'Pulse returned a grant without a version');
+    await writeOwnerOnlyJson(this.configFile, {
+      ...config,
+      capabilities,
+      paired: { ...config.paired, policyVersion: version },
+    });
+    return {
+      command: 'hub-write',
+      enabled: enable,
+      policyVersion: version,
+      changed: true,
+      message: enable
+        ? 'hub.write is on: Pulse can post, nudge, decide and accept on the local Agent Hub as you. The daemon picks up the new grant within a heartbeat.'
+        : 'hub.write is off: Pulse can no longer post to the local Agent Hub. Actions still queued for this machine expire.',
+    };
+  }
+
+  async stop({ revoke = false } = {}) {
+    const service = await this.serviceManager.stop();
+    let revoked = false;
+    if (revoke) {
+      const config = await this.#config();
+      if (config.paired) {
+        const paired = assertPairedConfig(config);
+        await writeOwnerOnlyJson(this.configFile, { ...config, paired: { ...config.paired, state: 'revoking' } });
+        const auth = new CloudAuth({
+          tokenStore: this.tokenStore,
+          fetch: this.fetch,
+          now: this.now,
+          target: {
+            platformUrl: paired.target.platformUrl,
+            devOrg: paired.target.devOrg,
+            instanceUrl: paired.baseUrl,
+            userId: paired.userId,
+            teamId: paired.teamId,
+          },
+        });
+        const response = await fetchJson({
+          fetch: this.fetch,
+          url: `${paired.baseUrl}${USER_API_BASE}/machines/${encodeURIComponent(paired.machineId)}/revoke`,
+          headers: await auth.credentials(),
+          body: { reason: 'Revoked from the connector' },
+        });
+        if (!response.ok && response.status !== 404) {
+          await writeOwnerOnlyJson(this.configFile, config);
+          throw new HubError(response.body.error || `HTTP_${response.status}`, response.body.message || 'Machine revocation failed');
+        }
+        await writeOwnerOnlyJson(this.configFile, { ...config, paired: null });
+        revoked = true;
+      }
+    }
+    return {
+      command: 'stop',
+      ...service,
+      revoked,
+      message: revoked ? 'Pulse connector stopped and machine revoked.' : 'Pulse connector stopped.',
+    };
+  }
+}
+
+let defaultApplication;
+
+export function getDefaultApplication() {
+  defaultApplication ||= new ConnectorApplication();
+  return defaultApplication;
+}

package/src/lib/backoff.js

@@ -0,0 +1,8 @@
+export function fullJitterDelay(
+  attempt,
+  { baseMs = 1_000, capMs = 60_000, random = Math.random } = {}
+) {
+  const exponent = Math.max(0, Math.min(30, Number(attempt) || 0));
+  const ceiling = Math.min(capMs, baseMs * 2 ** exponent);
+  return Math.floor(Math.max(0, Math.min(1, random())) * ceiling);
+}