auxilo-mcp 0.7.0 → 0.8.2

package/lib/installer.js

@@ -0,0 +1,647 @@
+'use strict';
+
+/**
+ * lib/installer.js — Turnkey installer core (LW-12)
+ *
+ * Testable core for the `auxilo setup|status|disable` CLI (bin/auxilo-cli.js).
+ * Every filesystem-touching function takes an explicit `homeDir` and every
+ * network-touching function takes an injectable `fetchImpl`, so unit tests run
+ * against fixture directories and mocked fetch — NEVER the real `~/.claude`
+ * or `~/.auxilo` (spec: specs/BUILD-SPEC-LAUNCH-WAVE.md §LW-12).
+ *
+ * Conventions inherited from scripts/runner.js (B15 / P1-13):
+ *   - Malformed client config JSON FAILS LOUDLY — never overwritten.
+ *   - Config writes are read-modify-write with tmp + rename.
+ *   - Executable surface installs to <home>/.auxilo/bin (NEVER ~/Documents — TCC).
+ *   - Credentials file is chmod 0600.
+ *
+ * NOTE: this module must not resolve the real home directory itself (no `os`
+ * module at all) — the CLI binding layer (bin/auxilo-cli.js) does that.
+ * Enforced by a source guard in test/lw12-installer.test.js.
+ *
+ * @module installer
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** MCP registration entry written into every client config (spec §LW-12 step 1). */
+const MCP_ENTRY = Object.freeze({ command: 'npx', args: ['auxilo-mcp'] });
+
+/** Default production API base (README.md / openapi.json servers[0]). */
+const DEFAULT_BASE_URL = 'https://api.auxilo.io';
+
+/** Root of the installed npm package (or the repo, when run from a clone). */
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Runner stack shipped in the npm tarball and copied into <home>/.auxilo/bin,
+ * preserving relative layout so runner.js's requires resolve
+ * (bin/scripts/runner.js → bin/lib/sensitivity-filter.js, bin/scripts/sources/).
+ * Mirrors the P1-13 sweeper file set (scripts/runner.js installSweeper) minus
+ * the launchd wrapper — LW-12 is hook-fired only; P1-13 owns the plist.
+ */
+const RUNNER_STACK = Object.freeze([
+  // [package-relative source, bin-relative dest, mode]
+  ['scripts/runner.js', 'scripts/runner.js', 0o755],
+  ['scripts/sources/source.interface.js', 'scripts/sources/source.interface.js', 0o644],
+  ['scripts/sources/claude-code.js', 'scripts/sources/claude-code.js', 0o644],
+  ['scripts/sources/openclaw.js', 'scripts/sources/openclaw.js', 0o644],
+  ['lib/sensitivity-filter.js', 'lib/sensitivity-filter.js', 0o644],
+]);
+
+// ─── Client registry + detection (spec §LW-12 step 1) ───────────────────────
+
+/**
+ * Build the supported-client registry for a given home directory.
+ *
+ * @param {string} homeDir   Explicit home directory (fixture dir in tests).
+ * @param {object} [opts]
+ * @param {string} [opts.platform=process.platform]  'darwin' | 'win32' | ...
+ * @param {object} [opts.env=process.env]            For %APPDATA% on win32.
+ * @returns {Array<object>} registry entries (detected or not)
+ */
+function clientRegistry(homeDir, opts = {}) {
+  if (!homeDir) throw new Error('clientRegistry: homeDir is required');
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+
+  const claudeDesktopDir = platform === 'win32'
+    ? path.join(env.APPDATA || path.join(homeDir, 'AppData', 'Roaming'), 'Claude')
+    : path.join(homeDir, 'Library', 'Application Support', 'Claude');
+
+  return [
+    {
+      id: 'claude-code',
+      name: 'Claude Code',
+      detectDir: path.join(homeDir, '.claude'),
+      configPath: path.join(homeDir, '.claude', 'settings.json'),
+      mcp: true,
+      hooks: true, // SessionEnd hook (background extraction)
+    },
+    {
+      id: 'claude-desktop',
+      name: 'Claude Desktop',
+      detectDir: claudeDesktopDir,
+      configPath: path.join(claudeDesktopDir, 'claude_desktop_config.json'),
+      mcp: true,
+      hooks: false,
+    },
+    {
+      id: 'cursor',
+      name: 'Cursor',
+      detectDir: path.join(homeDir, '.cursor'),
+      configPath: path.join(homeDir, '.cursor', 'mcp.json'),
+      mcp: true,
+      hooks: false,
+    },
+    {
+      id: 'openclaw',
+      name: 'OpenClaw',
+      detectDir: path.join(homeDir, '.openclaw'),
+      configPath: null, // no MCP config; poll-based source adapter (scripts/sources/openclaw.js)
+      mcp: false,
+      hooks: false,
+    },
+  ];
+}
+
+/**
+ * Detect which supported clients are present under homeDir.
+ * @returns {Array<object>} subset of clientRegistry whose detectDir exists
+ */
+function detectClients(homeDir, opts = {}) {
+  return clientRegistry(homeDir, opts).filter((c) => {
+    try {
+      return fs.statSync(c.detectDir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// ─── MCP registration (spec §LW-12 step 1) ──────────────────────────────────
+
+/** Atomic JSON write: tmp + rename (same convention as mcp-server.js setup). */
+function writeJsonAtomic(filePath, obj) {
+  const tmp = `${filePath}.tmp`;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * Read-parse a client config file. Malformed JSON throws (B15: fail loudly,
+ * never overwrite). Missing file returns {}.
+ */
+function readClientConfig(configPath) {
+  if (!fs.existsSync(configPath)) return {};
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  try {
+    return JSON.parse(raw);
+  } catch (parseErr) {
+    throw new Error(
+      `Malformed JSON in ${configPath} — refusing to overwrite. ` +
+      `Fix the file manually, then re-run \`auxilo setup\`. Parse error: ${parseErr.message}`
+    );
+  }
+}
+
+/**
+ * Register the Auxilo MCP server in one client's config file.
+ * Read-modify-write with tmp+rename; existing keys preserved; no-op (file
+ * untouched) when `mcpServers.auxilo` is already present.
+ *
+ * @param {object} client  Entry from clientRegistry (must have configPath).
+ * @returns {{ changed: boolean, status: 'registered'|'already-registered', configPath: string }}
+ * @throws on malformed existing JSON (caller skips that client loudly)
+ */
+function registerMcp(client) {
+  if (!client || !client.configPath) {
+    throw new Error(`registerMcp: client ${client && client.id} has no MCP config path`);
+  }
+  const config = readClientConfig(client.configPath);
+
+  if (config.mcpServers && config.mcpServers.auxilo) {
+    return { changed: false, status: 'already-registered', configPath: client.configPath };
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers.auxilo = { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] };
+  writeJsonAtomic(client.configPath, config);
+  return { changed: true, status: 'registered', configPath: client.configPath };
+}
+
+// ─── Credentials (spec §LW-12 step 2) ───────────────────────────────────────
+
+function credentialsPath(homeDir) {
+  return path.join(homeDir, '.auxilo', 'credentials.json');
+}
+
+/**
+ * Read ~/.auxilo/credentials.json. Returns null when absent/malformed
+ * (same tolerance as scripts/runner.js loadCredentials).
+ */
+function readCredentials(homeDir) {
+  try {
+    const creds = JSON.parse(fs.readFileSync(credentialsPath(homeDir), 'utf-8'));
+    return creds && typeof creds === 'object' ? creds : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write ~/.auxilo/credentials.json with mode 0600.
+ * Existing file is chmod 0600 BEFORE rewrite (spec), then replaced via
+ * tmp(0600) + rename so the secret never exists world-readable.
+ *
+ * @param {string} homeDir
+ * @param {{ api_key: string, base_url: string, email?: string, account_id?: string }} creds
+ * @returns {string} path written
+ */
+function writeCredentials(homeDir, creds) {
+  if (!homeDir) throw new Error('writeCredentials: homeDir is required');
+  if (!creds || !creds.api_key) throw new Error('writeCredentials: creds.api_key is required');
+
+  const credPath = credentialsPath(homeDir);
+  fs.mkdirSync(path.dirname(credPath), { recursive: true });
+
+  if (fs.existsSync(credPath)) fs.chmodSync(credPath, 0o600);
+
+  const tmp = `${credPath}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, credPath);
+  fs.chmodSync(credPath, 0o600); // belt-and-braces: rename preserves tmp mode, assert anyway
+  return credPath;
+}
+
+// ─── Device-code auth (spec §LW-12 step 2; server.js /auth/device) ──────────
+
+/**
+ * Run the device-code login flow against the Auxilo server.
+ * Pure network flow — does NOT write credentials (caller does, so an expired
+ * code can never leave a partial credentials file: T-LW12-11).
+ *
+ * @param {object} opts
+ * @param {string}   [opts.baseUrl=DEFAULT_BASE_URL]
+ * @param {Function} [opts.fetchImpl=fetch]    Injectable for tests.
+ * @param {Function} [opts.onCode]             (userCode, verificationUrl) → void; print/open browser.
+ * @param {Function} [opts.sleep]              (ms) → Promise; injectable for tests.
+ * @param {number}   [opts.maxWaitMs=600000]   10 min TTL (server DEVICE_CODE_TTL).
+ * @returns {Promise<{ api_key: string, account_id: string, email: string, base_url: string }>}
+ * @throws Error on expired code, HTTP failure, or timeout.
+ */
+async function deviceLogin(opts = {}) {
+  const baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const fetchImpl = opts.fetchImpl || fetch;
+  const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const maxWaitMs = opts.maxWaitMs !== undefined ? opts.maxWaitMs : 600000;
+
+  const res = await fetchImpl(`${baseUrl}/auth/device`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!res.ok) throw new Error(`Device code request failed (HTTP ${res.status})`);
+  const device = await res.json();
+  // A-1: device_code is the secret polling credential; user_code is the human
+  // code shown on the verification page only.
+  const { user_code: userCode, device_code: deviceCode, verification_url: verificationUrl } = device;
+  if (!userCode) throw new Error('Device code request failed: no user_code in response');
+  if (!deviceCode) throw new Error('Device code request failed: no device_code in response');
+
+  // Server returns interval in seconds (default 5 per server.js /auth/device).
+  const intervalMs = (device.interval || 5) * 1000;
+
+  if (typeof opts.onCode === 'function') opts.onCode(userCode, verificationUrl);
+
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() <= deadline) {
+    await sleep(intervalMs);
+    let status;
+    try {
+      const poll = await fetchImpl(`${baseUrl}/auth/device/status?device_code=${encodeURIComponent(deviceCode)}`);
+      status = await poll.json();
+    } catch {
+      continue; // transient network error during poll — keep polling
+    }
+    if (status.status === 'authorized') {
+      return {
+        api_key: status.api_key,
+        account_id: status.account_id,
+        email: status.email,
+        base_url: baseUrl,
+      };
+    }
+    if (status.status === 'expired') {
+      throw new Error('Device code expired — run `auxilo setup` again to get a new code.');
+    }
+    // pending → keep polling
+  }
+  throw new Error('Timed out waiting for device authorization (10 minutes).');
+}
+
+// ─── Runner install (spec §LW-12 step 3; layout per P1-13) ──────────────────
+
+function binRootFor(homeDir) {
+  return path.join(homeDir, '.auxilo', 'bin');
+}
+
+function hookScriptPathFor(homeDir) {
+  return path.join(binRootFor(homeDir), 'auxilo-extract.sh');
+}
+
+/**
+ * Generate the SessionEnd hook script body. Paths are embedded ABSOLUTELY
+ * (spec: hook references <home>/.auxilo/bin/scripts/runner.js absolutely).
+ * Logic mirrors the proven P2.1a hook: sentinel kill-switch, AUXILO_EXTRACTING
+ * recursion guard, detached spawn so session teardown is never blocked.
+ */
+function renderHookScript(homeDir) {
+  const auxiloDir = path.join(homeDir, '.auxilo');
+  const runnerPath = path.join(auxiloDir, 'bin', 'scripts', 'runner.js');
+  return `#!/bin/bash
+# Auxilo SessionEnd hook — generated by \`auxilo setup\` (LW-12).
+# Reads the Claude Code SessionEnd JSON from stdin, extracts the transcript
+# path, and spawns the extraction runner detached so shutdown is not blocked.
+# Re-run \`auxilo setup\` after upgrading the auxilo-mcp package.
+
+set -u
+
+# Kill-switch: runner fires only if the consent sentinel exists.
+#   enable:  auxilo setup (consent step)   disable: auxilo disable
+if [ ! -f "${auxiloDir}/autonomous-enabled" ]; then
+  exit 0
+fi
+
+# Recursion guard: bail if we're already inside an extraction chain.
+if [ "\${AUXILO_EXTRACTING:-0}" = "1" ]; then
+  exit 0
+fi
+
+input_json=$(cat)
+
+transcript_path=$(printf '%s' "$input_json" | /usr/bin/env node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{process.stdout.write(JSON.parse(d).transcript_path||"")}catch{}})' 2>/dev/null)
+
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  exit 0
+fi
+
+RUNNER="${runnerPath}"
+if [ ! -f "$RUNNER" ]; then
+  exit 0
+fi
+
+mkdir -p "${auxiloDir}"
+LOG="${auxiloDir}/extract.log"
+
+# Spawn detached — do not block session teardown.
+# P1-13 lesson: do NOT set AUXILO_EXTRACTING here — runner.js's own recursion
+# guard would trip and silently no-op every run. The runner sets it itself
+# for child processes.
+# LW-17: stdout goes to /dev/null — runner.js log() already appends every
+# line to extract.log itself; redirecting stdout there too double-wrote each
+# line and the daily digest double-counted. stderr still captured for crashes.
+nohup /usr/bin/env node "$RUNNER" --transcript "$transcript_path" > /dev/null 2>> "$LOG" &
+
+exit 0
+`;
+}
+
+/**
+ * Install the extraction runner stack into <home>/.auxilo/bin and generate
+ * the SessionEnd hook script (0755).
+ *
+ * Files are COPIED (not symlinked) from the npm package, preserving the
+ * relative layout runner.js requires. Missing package files throw — the lib
+ * never calls process.exit.
+ *
+ * @param {string} homeDir
+ * @param {object} [opts]
+ * @param {string} [opts.packageRoot=PACKAGE_ROOT]
+ * @returns {{ binRoot: string, hookPath: string, installed: string[] }}
+ */
+function installRunner(homeDir, opts = {}) {
+  if (!homeDir) throw new Error('installRunner: homeDir is required');
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  const binRoot = binRootFor(homeDir);
+  const installed = [];
+
+  for (const [src, dest, mode] of RUNNER_STACK) {
+    const srcPath = path.join(packageRoot, src);
+    const destPath = path.join(binRoot, dest);
+    if (!fs.existsSync(srcPath)) {
+      throw new Error(`installRunner: missing package file ${srcPath} — reinstall auxilo-mcp`);
+    }
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.copyFileSync(srcPath, destPath);
+    fs.chmodSync(destPath, mode);
+    installed.push(destPath);
+  }
+
+  const hookPath = hookScriptPathFor(homeDir);
+  fs.writeFileSync(hookPath, renderHookScript(homeDir));
+  fs.chmodSync(hookPath, 0o755);
+  installed.push(hookPath);
+
+  return { binRoot, hookPath, installed };
+}
+
+// ─── Claude Code hook registration (spec §LW-12 step 4) ─────────────────────
+
+/** True when an inner hook object is an Auxilo extraction command. */
+function isAuxiloCommandHook(h) {
+  return h && typeof h === 'object' && typeof h.command === 'string' &&
+    h.command.includes('auxilo-extract');
+}
+
+/**
+ * Patch <home>/.claude/settings.json hooks.SessionEnd[] to contain exactly one
+ * Auxilo entry: <home>/.auxilo/bin/auxilo-extract.sh, in Claude Code's
+ * STRUCTURED form ({ hooks: [{ type: 'command', command }] }).
+ *
+ * LW-17: 0.8.1 appended the command as a bare string — Claude Code silently
+ * ignores string entries, so the hook NEVER fired. It also only removed
+ * legacy entries that were strings, missing the pre-LW-12 structured entry
+ * (~/.claude/hooks/auxilo-extract.sh nested inside a matcher group).
+ *
+ * Idempotent. Removes every Auxilo reference (bare strings, and command
+ * objects inside matcher groups — preserving any non-Auxilo commands sharing
+ * the group), then appends one canonical structured entry. Non-Auxilo entries
+ * are preserved untouched. Malformed settings.json throws (B15) — never
+ * overwritten.
+ *
+ * @returns {{ changed: boolean, hookCmd: string, removedLegacy: string[] }}
+ */
+function registerClaudeCodeHook(homeDir) {
+  if (!homeDir) throw new Error('registerClaudeCodeHook: homeDir is required');
+  const settingsPath = path.join(homeDir, '.claude', 'settings.json');
+  const hookCmd = hookScriptPathFor(homeDir);
+
+  const settings = readClientConfig(settingsPath);
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
+
+  const before = settings.hooks.SessionEnd;
+  const removedLegacy = [];
+  const kept = [];
+
+  for (const entry of before) {
+    if (typeof entry === 'string' && entry.includes('auxilo-extract')) {
+      removedLegacy.push(entry); // includes 0.8.1's dead bare-string entry
+      continue;
+    }
+    if (entry && typeof entry === 'object' && Array.isArray(entry.hooks)) {
+      const auxilo = entry.hooks.filter(isAuxiloCommandHook);
+      if (auxilo.length > 0) {
+        removedLegacy.push(...auxilo.map((h) => h.command));
+        const rest = entry.hooks.filter((h) => !isAuxiloCommandHook(h));
+        if (rest.length > 0) kept.push({ ...entry, hooks: rest });
+        continue;
+      }
+    }
+    kept.push(entry);
+  }
+
+  const canonical = { hooks: [{ type: 'command', command: hookCmd }] };
+
+  // Idempotency: unchanged iff the only Auxilo reference found was already
+  // the canonical command in a structured single-command entry.
+  const alreadyExact =
+    removedLegacy.length === 1 && removedLegacy[0] === hookCmd &&
+    before.some((e) =>
+      e && typeof e === 'object' && Array.isArray(e.hooks) &&
+      e.hooks.length === 1 && isAuxiloCommandHook(e.hooks[0]) &&
+      e.hooks[0].command === hookCmd && e.hooks[0].type === 'command'
+    );
+  if (alreadyExact) {
+    return { changed: false, hookCmd, removedLegacy: [] };
+  }
+
+  settings.hooks.SessionEnd = [...kept, canonical];
+  writeJsonAtomic(settingsPath, settings);
+  return { changed: true, hookCmd, removedLegacy: removedLegacy.filter((c) => c !== hookCmd) };
+}
+
+// ─── Consent (spec §LW-12 step 5; server.js POST /extract/consent) ──────────
+
+/**
+ * Record extraction consent grant/revoke on the server.
+ *
+ * @param {object} opts
+ * @param {'grant'|'revoke'} opts.action
+ * @param {string}   opts.apiKey
+ * @param {string}   [opts.baseUrl=DEFAULT_BASE_URL]
+ * @param {Function} [opts.fetchImpl=fetch]
+ * @returns {Promise<object>} server response body
+ */
+async function recordConsent(opts = {}) {
+  const { action, apiKey } = opts;
+  if (action !== 'grant' && action !== 'revoke') {
+    throw new Error('recordConsent: action must be "grant" or "revoke"');
+  }
+  if (!apiKey) throw new Error('recordConsent: apiKey is required');
+  const baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const fetchImpl = opts.fetchImpl || fetch;
+
+  const res = await fetchImpl(`${baseUrl}/extract/consent`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+    body: JSON.stringify({ action }),
+  });
+  let body = {};
+  try { body = await res.json(); } catch { /* non-JSON error body */ }
+  if (!res.ok) {
+    throw new Error(`Consent ${action} failed (HTTP ${res.status}): ${body.error || 'unknown error'}`);
+  }
+  return body;
+}
+
+// ─── Kill-switch sentinel (spec §LW-12 step 5 / `auxilo disable`) ───────────
+
+function sentinelPath(homeDir) {
+  return path.join(homeDir, '.auxilo', 'autonomous-enabled');
+}
+
+function sentinelPresent(homeDir) {
+  return fs.existsSync(sentinelPath(homeDir));
+}
+
+/** Create the autonomous-extraction sentinel. Only called after explicit consent. */
+function enableSentinel(homeDir) {
+  const p = sentinelPath(homeDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `enabled ${new Date().toISOString()}\n`);
+  return p;
+}
+
+/** Remove the sentinel (local kill-switch). Returns true if it existed. */
+function disableSentinel(homeDir) {
+  const p = sentinelPath(homeDir);
+  if (!fs.existsSync(p)) return false;
+  fs.unlinkSync(p);
+  return true;
+}
+
+// ─── Status (spec §LW-12 `auxilo status`) ───────────────────────────────────
+
+/**
+ * Collect installer/extraction status for `auxilo status`.
+ * Network lookups are best-effort; everything else is local file probes.
+ *
+ * @param {string} homeDir
+ * @param {object} [opts]  { platform, env, fetchImpl }
+ * @returns {Promise<object>}
+ */
+async function getStatus(homeDir, opts = {}) {
+  if (!homeDir) throw new Error('getStatus: homeDir is required');
+  const fetchImpl = opts.fetchImpl || fetch;
+
+  // 1. Clients: detected + whether MCP registration is present
+  const clients = detectClients(homeDir, opts).map((c) => {
+    let registered = null; // null = not applicable (no MCP config)
+    if (c.mcp) {
+      registered = false;
+      try {
+        const config = JSON.parse(fs.readFileSync(c.configPath, 'utf-8'));
+        registered = Boolean(config.mcpServers && config.mcpServers.auxilo);
+      } catch { /* missing or malformed config → not registered */ }
+    }
+    return { id: c.id, name: c.name, mcp: c.mcp, registered };
+  });
+
+  // 2. Auth state
+  const creds = readCredentials(homeDir);
+  const auth = {
+    credentialsFile: fs.existsSync(credentialsPath(homeDir)),
+    keyPrefix: creds && creds.api_key ? `${String(creds.api_key).slice(0, 8)}…` : null,
+    email: (creds && creds.email) || null,
+    baseUrl: (creds && creds.base_url) || null,
+  };
+
+  // 3. Account mode (best-effort — server may be unreachable or route absent)
+  let accountMode = 'unknown';
+  if (creds && creds.api_key) {
+    try {
+      const res = await fetchImpl(`${(creds.base_url || DEFAULT_BASE_URL).replace(/\/+$/, '')}/account/settings`, {
+        headers: { 'X-API-Key': creds.api_key },
+      });
+      if (res.ok) {
+        const data = await res.json();
+        accountMode = data.autonomous_extraction_mode || 'off';
+      }
+    } catch { /* unreachable */ }
+  }
+
+  // 4. Sentinel + runner + hook install state
+  const hookPath = hookScriptPathFor(homeDir);
+  const runnerInstalled = fs.existsSync(path.join(binRootFor(homeDir), 'scripts', 'runner.js'));
+  let hookRegistered = false;
+  try {
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(homeDir, '.claude', 'settings.json'), 'utf-8')
+    );
+    // LW-17: only STRUCTURED entries count — Claude Code silently ignores
+    // bare-string entries (the 0.8.1 dead-hook bug), so reporting one as
+    // "registered" would mask exactly the failure this status exists to catch.
+    hookRegistered = Array.isArray(settings.hooks && settings.hooks.SessionEnd) &&
+      settings.hooks.SessionEnd.some((h) =>
+        h && typeof h === 'object' && Array.isArray(h.hooks) && h.hooks.some(isAuxiloCommandHook));
+  } catch { /* no settings */ }
+
+  // 5. Last extraction + pending queue (ledger conventions from scripts/runner.js)
+  let lastSweep = null;
+  try {
+    lastSweep = JSON.parse(
+      fs.readFileSync(path.join(homeDir, '.auxilo', 'ledger.json'), 'utf-8')
+    ).lastSweep || null;
+  } catch { /* no ledger yet */ }
+
+  let pendingCount = 0;
+  try {
+    pendingCount = fs.readdirSync(path.join(homeDir, '.auxilo', 'pending-learnings'))
+      .filter((f) => f.endsWith('.json')).length;
+  } catch { /* no queue dir yet */ }
+
+  return {
+    clients,
+    auth,
+    accountMode,
+    sentinel: sentinelPresent(homeDir),
+    runnerInstalled,
+    hookInstalled: fs.existsSync(hookPath),
+    hookRegistered,
+    lastSweep,
+    pendingCount,
+  };
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  MCP_ENTRY,
+  DEFAULT_BASE_URL,
+  PACKAGE_ROOT,
+  RUNNER_STACK,
+  clientRegistry,
+  detectClients,
+  registerMcp,
+  readClientConfig,
+  credentialsPath,
+  readCredentials,
+  writeCredentials,
+  deviceLogin,
+  binRootFor,
+  hookScriptPathFor,
+  renderHookScript,
+  installRunner,
+  registerClaudeCodeHook,
+  recordConsent,
+  sentinelPath,
+  sentinelPresent,
+  enableSentinel,
+  disableSentinel,
+  getStatus,
+};