@clearlysh/beehaven 0.8.16

package/dist/claude-credential-store.js

@@ -0,0 +1,633 @@
+/**
+ * claude-credential-store — daemon-side persistent storage for the
+ * user's Claude API key / plan token, written by the
+ * `canvas-credential-store` relay handler.
+ *
+ * Storage priority:
+ *   1. macOS Keychain via `security(1)` CLI — preferred. Stored under
+ *      service "clearly-claude-credential" + account "default", which
+ *      keeps it discoverable via Keychain Access.app and survives
+ *      OS reinstalls / disk migrations cleanly.
+ *   2. ~/.beehaven/claude-credentials JSON file with mode 600 —
+ *      fallback for non-macOS hosts OR when security(1) is unavailable
+ *      (e.g. inside containerised dev environments).
+ *
+ * The Agent SDK reads from one of these on each query() — see
+ * daemon-omni.ts's setup of `buildSdkOptions` (a future change will
+ * teach it to consult this store before falling back to
+ * ANTHROPIC_API_KEY env). For now, this module writes the value to BOTH
+ * the keychain AND the process env (`ANTHROPIC_API_KEY`) so the SDK
+ * picks it up on the very next turn without further changes.
+ *
+ * ── WHAT THIS STORE DOES NOT PERSIST ────────────────────────────────
+ *
+ * **Masked display strings.** A mask is a pure function of the secret,
+ * so it is DERIVED on every read, never written. Persisting it bought
+ * nothing and cost twice:
+ *
+ *   1. Drift. The keychain path always recomputed the mask and ignored
+ *      whatever was stored, while the file fallback trusted the stored
+ *      copy — two sources of truth for one string, guaranteed to
+ *      disagree the first time the format changed.
+ *   2. A real bug. The `plan` record was ONLY a mask, and that mask
+ *      carried a typographic ellipsis (U+2026). `security(1)` hex-encodes
+ *      any non-ASCII password on read, so `JSON.parse` threw and
+ *      readClaudeCredential() returned null for every plan credential
+ *      ever written on macOS — the lane looked disconnected after any
+ *      daemon restart. A presentation concern reached into the storage
+ *      layer and broke it.
+ *
+ * **Plan connection state.** `credType:'plan'` now stores NOTHING at
+ * all. We do not own that fact — `~/.claude/.credentials.json` does,
+ * written by Anthropic's own CLI. A stored marker was a cache of
+ * someone else's state with no invalidation: it survived `claude
+ * logout` and token expiry and kept reporting "connected". Plan status
+ * is now read live from that file on every call, so it cannot go stale.
+ *
+ * ⚠ Consequence worth knowing: "Disconnect" cannot revoke plan auth,
+ * because there is nothing of ours to delete. It clears any stored key
+ * and the env; revoking the subscription itself is `claude logout`.
+ */
+import { spawn } from 'node:child_process';
+import { promises as fs, watch as fsWatch, existsSync } from 'node:fs';
+import { homedir, platform, arch } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SERVICE = 'clearly-claude-credential';
+const ACCOUNT = 'default';
+const FALLBACK_DIR = join(homedir(), '.beehaven');
+const FALLBACK_FILE = join(FALLBACK_DIR, 'claude-credentials');
+/** Mask an API key for display. Derived, never stored. ASCII only —
+ *  a non-ASCII mask is what made `security(1)` hex-encode the record. */
+function maskKey(credType, key) {
+    // OpenRouter keeps more prefix ("sk-or-v1…") since users often have
+    // multiple OR keys and the prefix helps disambiguate.
+    const head = credType === 'openrouter-key' ? 10 : 8;
+    return `${key.slice(0, head)}...${key.slice(-4)}`;
+}
+/**
+ * Read the LIVE plan auth from Claude Code's own credentials file.
+ *
+ * This is the source of truth for "is a Claude subscription authorized
+ * on this machine" — we never copy it, cache it, or write it anywhere.
+ * Probes the canonical `.credentials.json` then the legacy
+ * `credentials.json` (no dot) that older Claude Code releases wrote.
+ *
+ * Returns null when no subscription auth is present.
+ */
+async function readLivePlanAuth() {
+    for (const path of [CLAUDE_CREDENTIALS_FILE, CLAUDE_CREDENTIALS_LEGACY_FILE]) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(path, 'utf8'));
+            const token = parsed?.claudeAiOauth?.accessToken;
+            if (typeof token === 'string' && token) {
+                return {
+                    maskedKey: `Pro/Max plan (...${token.slice(-4)})`,
+                    expiresAt: typeof parsed.claudeAiOauth.expiresAt === 'number'
+                        ? parsed.claudeAiOauth.expiresAt
+                        : undefined,
+                };
+            }
+        }
+        catch {
+            // Missing / mid-atomic-write / malformed — try the next location.
+        }
+    }
+    return null;
+}
+/** OpenRouter's Anthropic-compatible endpoint. The Anthropic Agent SDK
+ *  reads `ANTHROPIC_BASE_URL` to override its default api.anthropic.com
+ *  target — pointing it here routes the (otherwise identical) Anthropic-
+ *  protocol traffic through OpenRouter, which forwards to the underlying
+ *  Anthropic model (or any compatible Claude SKU) and bills against the
+ *  caller's OpenRouter account instead of an Anthropic account. */
+const OPENROUTER_ANTHROPIC_BASE_URL = 'https://openrouter.ai/api/v1';
+export async function storeClaudeCredential(input) {
+    const { credType, apiKey, planTokenHint } = input;
+    // ── plan: persist NOTHING ─────────────────────────────────────────
+    // Selecting the plan lane is not a write, it's a switch. Anthropic's
+    // CLI owns the token; all we do is get our key-based env out of the
+    // way so the `claude` auth chain falls through to subscription OAuth
+    // (ANTHROPIC_API_KEY outranks it), and drop any stored key so the old
+    // one can't win again on the next daemon restart.
+    //
+    // The mask we return is read LIVE from the credentials file, so the
+    // UI shows the token actually in force rather than a remembered one.
+    if (credType === 'plan') {
+        await deleteClaudeCredential(); // removes stored key + clears both env vars
+        const live = await readLivePlanAuth();
+        return {
+            storage: 'none',
+            maskedKey: live?.maskedKey ??
+                (planTokenHint ? `Pro/Max plan (...${planTokenHint})` : 'Pro/Max plan'),
+        };
+    }
+    if (!apiKey)
+        throw new Error(`apiKey required for ${credType} credType`);
+    const secretValue = apiKey;
+    // Derived for the return value only — never written. See the header.
+    const masked = maskKey(credType, apiKey);
+    // ── Try macOS Keychain first ──────────────────────────────────────
+    if (platform() === 'darwin') {
+        try {
+            // Delete any prior entry — security add-generic-password errors
+            // out if a duplicate (service, account) pair already exists. Idempotency
+            // via delete-then-add is simpler than detecting the prior state.
+            await runSecurity(['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT]).catch(() => { });
+            await runSecurity([
+                'add-generic-password',
+                '-s', SERVICE,
+                '-a', ACCOUNT,
+                '-w', secretValue,
+                '-U', // update if exists (belt + suspenders alongside the delete above)
+                // Description visible in Keychain Access — helps users understand
+                // what the entry is when they audit their keychain.
+                '-D', 'Clearly — Claude API key / plan auth',
+                '-j', 'Stored by the Hive Mac daemon for use by the Claude Agent SDK.',
+            ]);
+            // Also surface the secret to the daemon's process env so the
+            // CURRENT-PROCESS Agent SDK picks it up immediately. The next
+            // daemon restart will re-read from keychain (a future
+            // daemon-startup hook).
+            //
+            // For openrouter-key we ALSO set ANTHROPIC_BASE_URL so the
+            // Anthropic Agent SDK routes through OpenRouter's compat
+            // endpoint instead of api.anthropic.com; for a direct Anthropic
+            // key we clear it, so switching lanes can't strand a stale
+            // OpenRouter base URL that silently bills the wrong account.
+            process.env.ANTHROPIC_API_KEY = secretValue;
+            if (credType === 'openrouter-key') {
+                process.env.ANTHROPIC_BASE_URL = OPENROUTER_ANTHROPIC_BASE_URL;
+            }
+            else {
+                delete process.env.ANTHROPIC_BASE_URL;
+            }
+            return { storage: 'keychain', maskedKey: masked };
+        }
+        catch (err) {
+            // Fall through to filesystem fallback. Don't bubble — keychain
+            // unavailability is recoverable; we just lose the lifecycle bind.
+            // eslint-disable-next-line no-console
+            console.warn(`[claude-credential-store] keychain write failed, falling back to file: ${err?.message ?? err}`);
+        }
+    }
+    // ── Filesystem fallback ───────────────────────────────────────────
+    // Mode 600 — owner-only read/write. Survives daemon restarts; a
+    // future enhancement could encrypt with a machine-id-derived key.
+    await fs.mkdir(FALLBACK_DIR, { recursive: true });
+    // No maskedKey field — it is derived on read, same as the keychain
+    // path. Storing it here is what let the two paths drift.
+    const payload = {
+        credType,
+        secret: secretValue,
+        storedAt: Date.now(),
+    };
+    await fs.writeFile(FALLBACK_FILE, JSON.stringify(payload, null, 2), { mode: 0o600 });
+    // Same env handling as the keychain path above.
+    process.env.ANTHROPIC_API_KEY = secretValue;
+    if (credType === 'openrouter-key') {
+        process.env.ANTHROPIC_BASE_URL = OPENROUTER_ANTHROPIC_BASE_URL;
+    }
+    else {
+        delete process.env.ANTHROPIC_BASE_URL;
+    }
+    return { storage: 'file', maskedKey: masked };
+}
+/**
+ * readClaudeCredential — fetch the stored value back. Used by the
+ * daemon's startup hook to re-hydrate process.env on relaunch, and
+ * by an introspection RPC the settings panel uses to verify the
+ * keychain still has the entry.
+ *
+ * Returns null when nothing is stored.
+ */
+export async function readClaudeCredential() {
+    // macOS keychain first.
+    if (platform() === 'darwin') {
+        try {
+            const stdout = await runSecurity(['find-generic-password', '-s', SERVICE, '-a', ACCOUNT, '-w']);
+            const secret = stdout.trim();
+            if (!secret)
+                return null;
+            if (secret.startsWith('sk-or-')) {
+                return { credType: 'openrouter-key', secret, maskedKey: maskKey('openrouter-key', secret) };
+            }
+            if (secret.startsWith('sk-ant-')) {
+                return { credType: 'api-key', secret, maskedKey: maskKey('api-key', secret) };
+            }
+            // Anything else is a LEGACY plan marker — either readable JSON or,
+            // far more often, the hex `security(1)` emits for the non-ASCII
+            // ellipsis it contained (which is why these never read back). It
+            // holds no secret and no fact we can't get live, so drop it and
+            // let the live check below answer.
+            await deleteClaudeCredential();
+        }
+        catch {
+            // keychain miss — fall through to file fallback
+        }
+    }
+    // Filesystem fallback. Mask is DERIVED here too — reading a stored
+    // one is what let this path disagree with the keychain path.
+    try {
+        const raw = await fs.readFile(FALLBACK_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        const t = parsed?.credType;
+        if (parsed?.secret && (t === 'api-key' || t === 'openrouter-key')) {
+            return { credType: t, secret: parsed.secret, maskedKey: maskKey(t, parsed.secret) };
+        }
+        // Legacy plan marker in the file fallback — same treatment as the
+        // keychain one above.
+        if (t === 'plan')
+            await deleteClaudeCredential();
+    }
+    catch {
+        // file not present — no credential stored
+    }
+    // ── Nothing of ours is stored. Is a Claude subscription authorized
+    //    on this machine? Read it live; never cached, so it cannot be
+    //    stale after `claude logout` or a token expiry.
+    const live = await readLivePlanAuth();
+    if (live)
+        return { credType: 'plan', secret: '', maskedKey: live.maskedKey };
+    return null;
+}
+/**
+ * deleteClaudeCredential — remove from both keychain + fallback. Used
+ * by the `canvas-credential-disconnect` IPC path (future) so a
+ * worker-side disconnect propagates to the daemon's stored credential.
+ * Today the worker just clears its row; calling this from the worker
+ * side is a follow-up.
+ */
+export async function deleteClaudeCredential() {
+    if (platform() === 'darwin') {
+        await runSecurity(['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT]).catch(() => { });
+    }
+    try {
+        await fs.unlink(FALLBACK_FILE);
+    }
+    catch { /* idempotent */ }
+    // Clear ALL env vars the SDK could pick up — both the Anthropic
+    // key and any OpenRouter base-URL override. Leaving BASE_URL set
+    // after a disconnect would route a subsequent `claude login` Keychain
+    // token through OpenRouter (still valid, but bills against the wrong
+    // account silently).
+    delete process.env.ANTHROPIC_API_KEY;
+    delete process.env.ANTHROPIC_BASE_URL;
+}
+// ──────────────────────────────────────────────────────────────────────
+//   Plan-SDK OAuth — `claude setup-token` driver + credentials watcher
+// ──────────────────────────────────────────────────────────────────────
+//
+// The Anthropic Agent SDK plus the Claude Code CLI handle OAuth against
+// claude.ai natively. From our daemon we just need to:
+//   1. Find the `claude` binary (bundled with the Agent SDK as a
+//      platform-native optional dep, or installed at ~/.local/bin)
+//   2. Spawn `claude setup-token` — it opens the user's browser, runs
+//      the OAuth flow, and writes ~/.claude/.credentials.json on success
+//   3. Watch ~/.claude/.credentials.json for the post-auth state and
+//      notify the worker via canvas-credential-detected
+//
+// Per the May 13, 2026 Anthropic announcement + June 15, 2026 policy
+// change, third-party Agent SDK apps may now use this flow — usage
+// draws against the user's monthly Agent SDK credit pool ($20 Pro /
+// $100 Max 5x / $200 Max 20x) which is separate from interactive
+// limits. The OAuth flow itself is handled by Anthropic's CLI; we
+// just kick it off + listen for completion.
+const CLAUDE_CREDENTIALS_FILE = join(homedir(), '.claude', '.credentials.json');
+// Older Claude Code releases (and some `claude login` flows) wrote the
+// auth blob to ~/.claude/credentials.json — no dot prefix. The shape is
+// identical (`{ claudeAiOauth: { accessToken, refreshToken, expiresAt,
+// tokenType } }`); only the filename differs. We probe both locations so
+// users coming from the older path don't need to re-run `claude setup-
+// token` for the daemon to recognize their existing auth.
+const CLAUDE_CREDENTIALS_LEGACY_FILE = join(homedir(), '.claude', 'credentials.json');
+/**
+ * Locate the `claude` CLI binary the daemon can spawn. Resolution order:
+ *   1. Platform-native bundled binary from
+ *      `@anthropic-ai/claude-agent-sdk-{platform}-{arch}` (the SDK's optional native package)
+ *   2. `node_modules/.bin/claude` — if a sibling package installed one
+ *   3. System install at `~/.local/bin/claude` (Anthropic's installer default)
+ *   4. PATH lookup via `which claude`
+ *
+ * ⚠⚠ CANDIDATE 1 CANNOT RESOLVE TODAY, AND THIS DOCSTRING USED TO CLAIM THE OPPOSITE. It ended
+ * *"which will rarely happen since we bundle the SDK platform packages"* — we do not. The SDK
+ * declares eight optional platform packages and **none is installed anywhere in this monorepo**,
+ * so nothing is bundled and no electron-builder config copies one. The measured reason is size:
+ * the Claude Code runtime is ~200 MB per version against a 561 MB app, ~36% for one architecture.
+ *
+ * ⚠⚠ SO IN PRACTICE THIS RESOLVES AT STEP 3 OR 4 — the user's OWN Claude Code install. That is the
+ * BYOK model working as intended, but it means the capability is absent on a machine that has
+ * never installed Claude Code, and **the caller must say so plainly** rather than reporting a
+ * generic failure. A false claim in a docstring is worse than no docstring: it is why nobody
+ * checked.
+ *
+ * Returns null when nothing is found.
+ */
+export async function findClaudeBinary() {
+    const candidates = [];
+    // 1. SDK bundled platform-native binary. Resolve relative to this
+    //    module's location so it works regardless of cwd.
+    try {
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        const sdkRoot = join(moduleDir, '..', 'node_modules', '@anthropic-ai');
+        const nativePkg = `claude-agent-sdk-${platform()}-${arch()}`;
+        candidates.push(join(sdkRoot, nativePkg, 'claude'));
+        candidates.push(join(sdkRoot, nativePkg, 'bin', 'claude'));
+        // Also search up the tree — the Mac app's electron-builder unpacks
+        // node_modules into Resources/app.asar.unpacked
+        for (let depth = 2; depth <= 5; depth++) {
+            candidates.push(join(moduleDir, ...Array(depth).fill('..'), 'node_modules', '@anthropic-ai', nativePkg, 'claude'));
+        }
+    }
+    catch { /* file URL conversion failure — skip */ }
+    /**
+     * 2. A sibling `node_modules/.bin/claude`, resolved RELATIVE TO THIS MODULE.
+     *
+     * ⚠⚠ THIS WAS A HARDCODED ABSOLUTE PATH INTO ONE DEVELOPER'S HOME DIRECTORY —
+     * `~/projects/clearly/beehaven_sdk/packages/cli/node_modules/.bin/claude` — shipped inside a
+     * signed app. On that one machine it made the agent surface work for a reason no customer
+     * shares; on every other machine it is a guaranteed miss that costs a stat() and hides the real
+     * answer ("Claude Code is not installed") behind a path nobody recognises.
+     *
+     * Resolved from `import.meta.url` it means what it was trying to mean, in a checkout AND in a
+     * bundle, with nobody's username in it.
+     */
+    try {
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        for (let depth = 1; depth <= 4; depth++) {
+            candidates.push(join(moduleDir, ...Array(depth).fill('..'), 'node_modules', '.bin', 'claude'));
+        }
+    }
+    catch { /* file URL conversion failure — skip */ }
+    // 3. User-level install (Anthropic's installer default)
+    candidates.push(join(homedir(), '.local', 'bin', 'claude'));
+    candidates.push(join(homedir(), '.local', 'share', 'claude', 'bin', 'claude'));
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    // 4. Last-resort PATH lookup
+    return new Promise((resolve) => {
+        const child = spawn('which', ['claude'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let out = '';
+        child.stdout.on('data', (d) => { out += d.toString('utf8'); });
+        child.on('close', (code) => {
+            const path = out.trim();
+            resolve(code === 0 && path ? path : null);
+        });
+        child.on('error', () => resolve(null));
+    });
+}
+/**
+ * Spawn `claude setup-token` to kick off the plan-SDK OAuth flow.
+ *
+ * The CLI opens the user's default browser to claude.com OAuth, waits
+ * for the user to authorize, and writes ~/.claude/.credentials.json
+ * with the `claudeAiOauth` block on success. Our daemon doesn't block
+ * on subprocess completion — we let it run in the background. The
+ * companion file watcher detects the credentials file mutation and
+ * notifies the worker.
+ *
+ * Returns the subprocess PID so callers can ack the launch back to
+ * the worker (the UI shows "browser tab opening / authorize there").
+ * If the subprocess exits with an error code, we surface stderr so
+ * users get diagnostic information.
+ */
+export async function startPlanOauth(opts) {
+    const binary = await findClaudeBinary();
+    if (!binary) {
+        return {
+            ok: false,
+            error: 'Could not find the Claude Code binary. Install at https://claude.com/download or via the Mac app reinstall.',
+        };
+    }
+    let child;
+    try {
+        child = spawn(binary, ['setup-token'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Inherit env so the subprocess can read the user's existing
+            // ~/.claude/ config + open their browser via xdg-open / open.
+            env: { ...process.env },
+            detached: false,
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `Could not spawn claude setup-token: ${err?.message ?? err}` };
+    }
+    // Accumulate stderr for diagnostic surfacing if the subprocess fails.
+    let stderrTail = '';
+    child.stdout?.on('data', (d) => {
+        const chunk = d.toString('utf8');
+        if (opts?.onOutput)
+            opts.onOutput(chunk);
+    });
+    child.stderr?.on('data', (d) => {
+        const chunk = d.toString('utf8');
+        stderrTail = (stderrTail + chunk).slice(-2000); // bounded buffer
+        if (opts?.onOutput)
+            opts.onOutput(chunk);
+    });
+    child.on('exit', (code) => {
+        if (opts?.onExit)
+            opts.onExit(code, stderrTail);
+    });
+    return { ok: true, pid: child.pid ?? -1, binary };
+}
+/**
+ * Read Claude Code's auth file from whichever location currently holds it.
+ *
+ * Tries the canonical `.credentials.json` first; falls back to the legacy
+ * `credentials.json` (no dot) that older Claude Code releases used. When
+ * only the legacy path has a credential, best-effort symlinks it to the
+ * canonical path so the Anthropic Agent SDK — which hard-codes
+ * `~/.claude/.credentials.json` — picks up the same token without the
+ * user re-running `claude setup-token`. Symlink failure is non-fatal:
+ * we still return the parsed credential so the worker-side gate
+ * (workspace.ts `agent:claude-prompt` cred check) gets notified; only
+ * the SDK side stays broken until the symlink can be created.
+ *
+ * Returns { parsed, sourcePath } on hit, null on miss.
+ */
+async function readClaudeCodeAuthFile() {
+    // Canonical first.
+    try {
+        const raw = await fs.readFile(CLAUDE_CREDENTIALS_FILE, 'utf8');
+        return { parsed: JSON.parse(raw), sourcePath: CLAUDE_CREDENTIALS_FILE };
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    // Legacy fallback — bridge to canonical via symlink so the SDK sees it.
+    try {
+        const raw = await fs.readFile(CLAUDE_CREDENTIALS_LEGACY_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        try {
+            await fs.symlink(CLAUDE_CREDENTIALS_LEGACY_FILE, CLAUDE_CREDENTIALS_FILE);
+            // eslint-disable-next-line no-console
+            console.log(`[claude-credential-store] bridged legacy auth: symlinked ${CLAUDE_CREDENTIALS_LEGACY_FILE} → ${CLAUDE_CREDENTIALS_FILE}`);
+        }
+        catch (linkErr) {
+            // EEXIST means the canonical file was created in the gap between
+            // our canonical-read above (which returned ENOENT) and the symlink
+            // attempt — race with `claude setup-token` running concurrently.
+            // Harmless: re-read on the next watcher tick. Anything else (EACCES,
+            // EROFS, etc.) we surface so the operator knows the SDK side won't
+            // pick up the token even though the worker side will.
+            if (linkErr?.code !== 'EEXIST') {
+                // eslint-disable-next-line no-console
+                console.warn(`[claude-credential-store] could not symlink ${CLAUDE_CREDENTIALS_LEGACY_FILE} → ${CLAUDE_CREDENTIALS_FILE}: ${linkErr?.message ?? linkErr}`);
+            }
+        }
+        return { parsed, sourcePath: CLAUDE_CREDENTIALS_LEGACY_FILE };
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/**
+ * Watch ~/.claude/.credentials.json (and the legacy `credentials.json`)
+ * and fire onDetected whenever a `claudeAiOauth.accessToken` appears
+ * (or changes).
+ *
+ * Implementation notes:
+ *   - fs.watch on the parent dir, filtered to either credentials
+ *     filename. Watching files directly is fragile because the CLI
+ *     uses atomic-write (write to a temp file, rename over) which fires
+ *     'rename' events the file watcher can't track.
+ *   - Coalesce events with a small debounce — atomic writes typically
+ *     produce 2-3 events back-to-back.
+ *   - We don't track per-token changes; the worker only cares about
+ *     "from no token → token present" transitions (treats subsequent
+ *     refreshes as no-ops).
+ *
+ * Returns an unsubscribe function the caller invokes to stop the watch.
+ */
+export function watchClaudeCredentialsFile(onDetected) {
+    const dir = dirname(CLAUDE_CREDENTIALS_FILE);
+    const canonicalFilename = '.credentials.json';
+    const legacyFilename = 'credentials.json';
+    let lastSeenKey = null;
+    let debounceTimer = null;
+    const evaluate = async () => {
+        try {
+            const result = await readClaudeCodeAuthFile();
+            if (!result) {
+                // No credential in either location. Reset state so a subsequent
+                // appearance is treated as a new event.
+                lastSeenKey = null;
+                return;
+            }
+            const parsed = result.parsed;
+            // Plan-SDK OAuth shape: { claudeAiOauth: { accessToken, refreshToken, expiresAt, scopes } }
+            if (parsed?.claudeAiOauth?.accessToken) {
+                const token = String(parsed.claudeAiOauth.accessToken);
+                if (token === lastSeenKey)
+                    return; // no change
+                lastSeenKey = token;
+                const masked = `Pro/Max plan (…${token.slice(-4)})`;
+                onDetected({
+                    type: 'plan',
+                    maskedKey: masked,
+                    expiresAt: typeof parsed.claudeAiOauth.expiresAt === 'number' ? parsed.claudeAiOauth.expiresAt : undefined,
+                    scopes: Array.isArray(parsed.claudeAiOauth.scopes) ? parsed.claudeAiOauth.scopes : undefined,
+                });
+                return;
+            }
+            // API-key shape: { primaryApiKey: 'sk-ant-...' } or similar — included for
+            // completeness if a user runs `claude --api-key`. Treated as 'api-key' type.
+            if (typeof parsed?.primaryApiKey === 'string' && parsed.primaryApiKey.startsWith('sk-ant-')) {
+                const key = parsed.primaryApiKey;
+                if (key === lastSeenKey)
+                    return;
+                lastSeenKey = key;
+                onDetected({
+                    type: 'api-key',
+                    maskedKey: `${key.slice(0, 8)}...${key.slice(-4)}`,
+                });
+            }
+        }
+        catch {
+            // Parse errors are normal during atomic-write windows; ignore.
+        }
+    };
+    // Initial poll in case the file already exists.
+    evaluate();
+    let watcher;
+    try {
+        watcher = fsWatch(dir, { persistent: false }, (_event, name) => {
+            if (name !== canonicalFilename && name !== legacyFilename)
+                return;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(evaluate, 200);
+        });
+    }
+    catch (err) {
+        // ~/.claude/ may not exist yet (fresh install). Create it then watch.
+        // If creation fails too, we silently no-op — the OAuth flow will
+        // create the dir on first run, and a future call to this function
+        // can succeed.
+        try {
+            const fsSync = require('node:fs');
+            fsSync.mkdirSync(dir, { recursive: true });
+            watcher = fsWatch(dir, { persistent: false }, (_event, name) => {
+                if (name !== canonicalFilename && name !== legacyFilename)
+                    return;
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(evaluate, 200);
+            });
+        }
+        catch {
+            return () => { };
+        }
+    }
+    return () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        try {
+            watcher.close();
+        }
+        catch { /* idempotent */ }
+    };
+}
+// ── Internal: security(1) wrapper ────────────────────────────────────
+function runSecurity(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('security', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (d) => { out += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { err += d.toString('utf8'); });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(out);
+                return;
+            }
+            /**
+             * ⚠⚠ "NOT FOUND" IS AN ABSENCE, NOT A FAILURE — and reporting it as one is where the scary
+             * keychain text comes from. `security` exits 44 with
+             *
+             *     security: SecKeychainSearchCopyNext: The specified item could not be found in the keychain.
+             *
+             * for the perfectly ordinary case of reading a secret that was never stored, or deleting one
+             * that is already gone. Rejecting on it turns a routine miss into an error a user reads as
+             * "the keychain is broken" — and callers then log it, because from their side it arrived as a
+             * thrown Error rather than an empty answer.
+             *
+             * ⚠ ONLY THE NOT-FOUND CODE. A real failure — locked keychain, denied access, malformed
+             * arguments — still rejects with the full text, because those are the cases where the
+             * message is the whole diagnosis.
+             */
+            if (code === 44 || /could not be found in the keychain/i.test(err)) {
+                resolve('');
+                return;
+            }
+            reject(new Error(`security ${args[0]} failed (${code}): ${err.trim() || '(no stderr)'}`));
+        });
+        child.on('error', reject);
+    });
+}