@askalf/dario 6.0.12 → 6.0.13

package/dist/doctor-core.js

@@ -0,0 +1,1234 @@
+/**
+ * dario doctor — health report aggregator.
+ *
+ * Runs every check we know how to run and returns a list of labelled
+ * results. The CLI passes the result list through `formatChecks` for
+ * display; `runChecks` is the I/O-heavy collector, `formatChecks` is a
+ * pure function the tests exercise directly.
+ *
+ * Keep `runChecks` defensive: a check that throws must not take the
+ * rest of the report down — every check is wrapped so a broken sub-
+ * system surfaces as `fail` instead of crashing the CLI.
+ */
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir, platform, arch, release } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { CC_TEMPLATE, resolveSystemPrompt, } from './cc-template.js';
+import { describeTemplate, detectDrift, checkCCCompat, findInstalledCC, missingVariantFamilies, SUPPORTED_CC_RANGE, CURRENT_SCHEMA_VERSION, compareVersions, VARIANT_FAMILIES, } from './live-fingerprint.js';
+import { detectCCOAuthConfig } from './cc-oauth-detect.js';
+import { runAuthorizeProbe } from './cc-authorize-probe.js';
+import { MIGRATED_LOGIN_ALIAS } from './accounts.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Decide what `doctor` should say about pool-exhaustion failover, from
+ * configuration alone. Pure and exported so every branch is testable — the
+ * live box can only ever exercise the one that matches its own credentials,
+ * which is how the inert case went unnoticed in the first place.
+ *
+ * This check exists because of a specific outage. The box ran with
+ * --pool-fallback armed, no Codex account and no api-key backend, so failover
+ * was INERT: correctly configured by every check that existed, and incapable of
+ * doing anything. On 2026-08-29 the Claude pool filled twice and the fleet went
+ * dark beside an idle ChatGPT subscription. Nothing reported it, because
+ * nothing asked "armed" and "has somewhere to go" as a single question.
+ *
+ * It reports configuration, never reachability. Claiming a route WORKS needs a
+ * live request, and this release was built on the lesson that a green config is
+ * not a working path.
+ */
+export function failoverReadiness(input) {
+    const { chain, codexAccounts, backends } = input;
+    const hasCodex = codexAccounts > 0;
+    const hasBackend = backends.length > 0;
+    if (chain.length === 0) {
+        return { status: 'info', detail: 'off — a drained Claude pool returns 429/503 (--pool-fallback to arm)' };
+    }
+    if (!hasCodex && !hasBackend) {
+        return {
+            status: 'warn',
+            detail: `armed (${chain.join(' → ')}) but INERT — no Codex account and no backend to fall back to. `
+                + 'Add one: `dario add altman` (subscription) or `dario backend add …` (api key).',
+        };
+    }
+    if (hasCodex && chain.length > 1) {
+        return {
+            status: 'ok',
+            detail: `symmetric: ${chain.join(' → ')}, across ${codexAccounts} Codex account`
+                + `${codexAccounts === 1 ? '' : 's'}${hasBackend ? ` + ${backends.length} backend(s)` : ''}`,
+        };
+    }
+    if (hasCodex) {
+        return {
+            status: 'ok',
+            detail: `claude → codex as ${chain[0]} (both wire shapes). One-way — add a Claude model to `
+                + 'the chain (--pool-fallback=a,b) to cover a rate-limited ChatGPT plan too.',
+        };
+    }
+    return {
+        status: 'ok',
+        detail: `claude → ${backends[0]} as ${chain[0]} — OpenAI path only. A Codex account would `
+            + 'extend it to Anthropic-shape clients (Claude Code, agent runtimes).',
+    };
+}
+/**
+ * Format a epoch timestamp reset time relative to the current time.
+ * Returns a human-friendly string like "1h 9m", "45m", "2d 3h".
+ */
+export function formatReset(resetEpochSecs, nowMs) {
+    const ms = (resetEpochSecs * 1000) - nowMs;
+    if (ms <= 0)
+        return '0m';
+    const totalMins = Math.round(ms / 60000);
+    if (totalMins <= 0)
+        return '0m';
+    const days = Math.floor(totalMins / 1440);
+    const hours = Math.floor((totalMins % 1440) / 60);
+    const mins = totalMins % 60;
+    if (days > 0) {
+        return `${days}d ${hours}h`;
+    }
+    if (hours > 0) {
+        return `${hours}h ${mins}m`;
+    }
+    return `${mins}m`;
+}
+/**
+ * Pretty-print a list of Check results as aligned ASCII. No color codes —
+ * Windows cmd / CI logs render plain text reliably; colors are a downside
+ * not an upside for a report that's often piped or pasted.
+ */
+export function formatChecks(checks) {
+    const prefix = {
+        ok: '[ OK ]',
+        warn: '[WARN]',
+        fail: '[FAIL]',
+        info: '[INFO]',
+    };
+    const labelWidth = checks.reduce((n, c) => Math.max(n, c.label.length), 0);
+    const lines = checks.map((c) => `  ${prefix[c.status]}  ${c.label.padEnd(labelWidth)}  ${c.detail}`);
+    return lines.join('\n');
+}
+/**
+ * Derive a CLI exit code from a set of check results. Any `fail` → 1.
+ * `warn` alone does not fail — we don't want `dario doctor` to CI-fail
+ * a user's machine just because they're on an untested CC version.
+ */
+export function exitCodeFor(checks) {
+    return checks.some((c) => c.status === 'fail') ? 1 : 0;
+}
+/**
+ * Serialize a check report as structured JSON. Lets other tools
+ * (claude-bridge's /status command, deepdive, CI scripts) consume
+ * dario's health programmatically instead of scraping the formatted
+ * text. Emitted by `dario doctor --json`.
+ */
+export function formatChecksJson(checks) {
+    const summary = {
+        ok: checks.filter((c) => c.status === 'ok').length,
+        warn: checks.filter((c) => c.status === 'warn').length,
+        fail: checks.filter((c) => c.status === 'fail').length,
+        info: checks.filter((c) => c.status === 'info').length,
+    };
+    return JSON.stringify({
+        generatedAt: new Date().toISOString(),
+        exitCode: exitCodeFor(checks),
+        summary,
+        checks,
+    }, null, 2);
+}
+/**
+ * The OAuth doctor row, as a pure decision — mirrors checkIdentityDrift so the
+ * branch logic is unit-testable without touching the filesystem.
+ *
+ * WHY THIS EXISTS. The legacy `credentials.json` is not what serves once an
+ * account pool exists: dario#805 deliberately keeps a NEWER pool token and
+ * refuses to overwrite that file, so "credentials.json is stale" is an expected
+ * steady state — every recovery that restores a pool account leaves one behind.
+ * Reporting that as `OAuth expired` while the pool answers every request is a
+ * false alarm, and dario-doctor-watch opens an issue for it on EVERY run:
+ * dario#1105 was filed while a live probe was returning 200 on both Haiku and
+ * Sonnet. A watcher that cries wolf on a healthy proxy trains its reader to
+ * ignore it, which is the failure the watcher exists to prevent.
+ *
+ * So: a live pool overrides a dead legacy file (and says so, rather than hiding
+ * it), and only "nothing can serve" is reported as a failure.
+ */
+export function oauthCheckRow(input) {
+    const { legacyStatus, legacyCanRefresh, poolHealthy, poolTotal } = input;
+    if (poolHealthy > 0) {
+        return {
+            status: 'ok',
+            label: 'OAuth',
+            detail: `pool credential live (${poolHealthy}/${poolTotal} account${poolTotal === 1 ? '' : 's'}) — ` +
+                `the legacy credentials.json is ${legacyStatus} and unused (dario#805)`,
+        };
+    }
+    return {
+        status: legacyStatus === 'expired' && legacyCanRefresh ? 'warn' : 'fail',
+        label: 'OAuth',
+        detail: legacyStatus === 'none' ? 'not authenticated — run `dario login`' : legacyStatus,
+    };
+}
+export function checkIdentityDrift(input) {
+    const { live, poolAccounts } = input;
+    // Short-prefix for surfaced IDs — 64-char userIDs and 36-char UUIDs are
+    // noisy in a doctor report. Operators only need enough to recognize / diff
+    // by eye; full values stay in the source files.
+    const shortId = (s) => (s ? `${s.slice(0, 8)}…` : '(empty)');
+    if (!live || (!live.deviceId && !live.accountUuid)) {
+        return [{
+                status: 'info',
+                label: 'Identity',
+                detail: 'no ~/.claude.json found — proxy will send requests without metadata.user_id, which routes them to Extra Usage billing instead of the Max plan allocation. Run Claude Code at least once to generate it.',
+            }];
+    }
+    if (poolAccounts.length === 0) {
+        return [{
+                status: 'info',
+                label: 'Identity',
+                detail: `~/.claude.json userID=${shortId(live.deviceId)} — no pool accounts snapshotted yet, so identity drift can't be checked. It starts once the login pool-of-one is materialized (\`dario login\` / \`dario proxy\`) or you \`dario accounts add\` more; until then a mismatch only surfaces as a 401 from Anthropic on non-Haiku models.`,
+            }];
+    }
+    const aligned = [];
+    const drifted = [];
+    const driftedAliases = [];
+    for (const acc of poolAccounts) {
+        const deviceMatch = acc.deviceId === live.deviceId;
+        const acctMatch = acc.accountUuid === live.accountUuid;
+        if (deviceMatch && acctMatch) {
+            aligned.push(acc.alias);
+        }
+        else {
+            const which = !deviceMatch && !acctMatch ? 'both' : !deviceMatch ? 'deviceId' : 'accountUuid';
+            drifted.push(`${acc.alias} (${which})`);
+            driftedAliases.push(acc.alias);
+        }
+    }
+    if (drifted.length === 0) {
+        return [{
+                status: 'ok',
+                label: 'Identity',
+                detail: `${aligned.length}/${poolAccounts.length} pool account${poolAccounts.length === 1 ? '' : 's'} match ~/.claude.json (userID=${shortId(live.deviceId)})`,
+            }];
+    }
+    // The remedy is deliberately NOT `accounts add <alias>`. That command
+    // exits 1 on an alias that already exists ("Remove it first"), and its
+    // default path runs a full OAuth browser flow rather than re-snapshotting
+    // — so naming it here walked every drifted user into a dead end. The two
+    // alias kinds genuinely need different commands: the reserved login alias
+    // is back-filled from whatever credentials are current, so removing it is
+    // enough (it re-materializes on the next `dario login` / `dario proxy`),
+    // while a user-added alias has to be removed and re-added, which re-runs
+    // OAuth for that account by design.
+    const loginDrifted = driftedAliases.includes(MIGRATED_LOGIN_ALIAS);
+    const otherDrifted = driftedAliases.filter((a) => a !== MIGRATED_LOGIN_ALIAS);
+    const fixes = [];
+    if (loginDrifted) {
+        fixes.push(`\`dario accounts remove ${MIGRATED_LOGIN_ALIAS}\` — it re-materializes from your ` +
+            `current credentials on the next \`dario login\` / \`dario proxy\``);
+    }
+    if (otherDrifted.length > 0) {
+        fixes.push(`\`dario accounts remove <alias>\` then \`dario accounts add <alias>\` to re-snapshot` +
+            `${otherDrifted.length === 1 ? '' : ' (for each of them)'} — the add re-runs OAuth for that account`);
+    }
+    return [{
+            status: 'warn',
+            label: 'Identity',
+            detail: `${drifted.length}/${poolAccounts.length} pool account${poolAccounts.length === 1 ? '' : 's'} drifted from ~/.claude.json (live userID=${shortId(live.deviceId)}): ${drifted.join('; ')} — non-Haiku requests on the drifted account(s) will 401. Fix: ${fixes.join('; ')}`,
+        }];
+}
+/**
+ * Ask npm for the latest @anthropic-ai/claude-code version. One 3s
+ * timeout; failures return null so doctor silently drops the check.
+ * Result is cached module-scoped so back-to-back doctor invocations
+ * (e.g. from a wrapping script) don't hammer the npm registry.
+ */
+let _npmLatestCache = null;
+const NPM_CACHE_TTL_MS = 60 * 1000;
+export function probeNpmLatestCC() {
+    if (_npmLatestCache && Date.now() - _npmLatestCache.at < NPM_CACHE_TTL_MS) {
+        return _npmLatestCache.value;
+    }
+    let value = null;
+    try {
+        // `npm view <pkg> version` prints the version as a single line.
+        // 3s timeout keeps doctor responsive even with flaky network /
+        // corporate proxies; stdio ignores stderr so "npm notice" banners
+        // don't pollute stdout parsing.
+        const out = execFileSync('npm', ['view', '@anthropic-ai/claude-code', 'version'], {
+            encoding: 'utf-8',
+            timeout: 3_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            // npm ships as .cmd on Windows; execFile can't spawn it directly
+            // without shell:true. `npm` is not user-overridable here so the
+            // command-injection risk is nil.
+            shell: process.platform === 'win32',
+        });
+        const m = /(\d+\.\d+\.\d+(?:[.\-][\w.\-]+)?)/.exec(out);
+        value = m ? m[1] : null;
+    }
+    catch {
+        value = null;
+    }
+    _npmLatestCache = { value, at: Date.now() };
+    return value;
+}
+/**
+ * One representative model per family, shared by the `--usage` probe
+ * (Anthropic only returns a family's 7d bucket header on a request TO
+ * that family) and the `--obedience` probe (behavioral drift is
+ * per-family — the 2026-06-12 regression hit sonnet while haiku obeyed
+ * the identical merged body).
+ */
+const PROBE_FAMILIES = [
+    { family: 'haiku', model: 'claude-haiku-4-5' },
+    { family: 'sonnet', model: 'claude-sonnet-5' },
+    { family: 'opus', model: 'claude-opus-5' },
+    { family: 'fable', model: 'claude-fable-5' },
+];
+/**
+ * The client system prompt the `--obedience` probe sends. Deliberately
+ * trivial: any model that weighs client system text at all can comply,
+ * so a miss isolates "the client system prompt is being ignored" from
+ * "the instruction was too hard".
+ */
+export const OBEDIENCE_SYSTEM_PROMPT = 'Reply with ONLY the word PONG. No other words, no punctuation, no formatting.';
+/**
+ * Join the text blocks of a `/v1/messages` response body. Thinking
+ * blocks are excluded — adaptive thinking may prepend them and they are
+ * not part of what the client-facing instruction governs. A refusal
+ * (empty content) or a malformed body yields ''.
+ */
+export function extractMessageText(body) {
+    const content = body?.content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+}
+/**
+ * Verdict for one obedience reply. Lenient on case and a single trailing
+ * `.`/`!` — the drift class this detects is "the model ignored the client
+ * system prompt entirely" (it answers as the CC persona instead), and a
+ * stray "Pong!" is obedient in substance. Strict equality would file
+ * 6-hourly drift issues over punctuation sampling.
+ */
+export function isObedientReply(text) {
+    return /^pong[.!]?$/i.test(text.trim());
+}
+/**
+ * Run every available health check. Never throws — each check is
+ * individually try/caught so a broken subsystem (e.g. unreadable accounts
+ * dir) shows up as a `fail` row instead of crashing the CLI.
+ *
+ * The order is curated — more fundamental checks first (Node, dario
+ * version, platform) so a reader scanning the output top-down sees
+ * the environment before the subsystems.
+ */
+export async function runChecks(opts = {}) {
+    const checks = [];
+    // ---- dario version
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+        checks.push({ status: 'info', label: 'dario', detail: `v${pkg.version}` });
+    }
+    catch {
+        checks.push({ status: 'warn', label: 'dario', detail: 'package.json not readable — version unknown' });
+    }
+    // ---- Node
+    checks.push({
+        status: nodeStatus(),
+        label: 'Node',
+        detail: process.version,
+    });
+    // ---- Platform
+    checks.push({
+        status: 'info',
+        label: 'Platform',
+        detail: `${platform()} ${arch()} (${release()})`,
+    });
+    // ---- Runtime TLS fingerprint (v3.23, direction #3)
+    // Proxy mode terminates TLS in this process, so Bun-vs-Node is a
+    // fingerprint axis Anthropic can read directly off the wire.
+    try {
+        const { detectRuntimeFingerprint } = await import('./runtime-fingerprint.js');
+        const rt = detectRuntimeFingerprint();
+        const status = rt.status === 'bun-match' ? 'ok' : 'warn';
+        checks.push({
+            status,
+            label: 'Runtime / TLS',
+            detail: rt.hint ? `${rt.detail}. ${rt.hint}` : rt.detail,
+        });
+    }
+    catch (err) {
+        checks.push({
+            status: 'warn',
+            label: 'Runtime / TLS',
+            detail: `check failed: ${err.message}`,
+        });
+    }
+    // ---- CC binary
+    const cc = safely(() => findInstalledCC(), { path: null, version: null });
+    if (cc.path && cc.version) {
+        const compat = checkCCCompat(cc.version);
+        const status = compat.status === 'ok' ? 'ok' :
+            compat.status === 'untested-above' ? 'warn' :
+                compat.status === 'below-min' ? 'fail' :
+                    'warn';
+        checks.push({
+            status,
+            label: 'CC binary',
+            detail: `v${cc.version} at ${cc.path}  (range: v${SUPPORTED_CC_RANGE.min} – v${SUPPORTED_CC_RANGE.maxTested})`,
+        });
+        // Stale-upstream probe: compare installed against npm's @latest.
+        // One network hop (3s timeout, 60s in-process cache). Silent on
+        // failure — no check row emitted — since a flaky network
+        // shouldn't turn doctor's output noisy. Only emits when the
+        // installed CC is strictly older than the npm latest.
+        try {
+            const npmLatest = probeNpmLatestCC();
+            if (npmLatest && compareVersions(cc.version, npmLatest) < 0) {
+                checks.push({
+                    status: 'info',
+                    label: 'CC upstream',
+                    detail: `npm latest is v${npmLatest} — installed is v${cc.version}. ` +
+                        `Run \`npm install -g @anthropic-ai/claude-code@latest\` to upgrade; ` +
+                        `dario's template will re-capture automatically on next startup.`,
+                });
+            }
+        }
+        catch { /* silent */ }
+    }
+    else if (cc.path) {
+        checks.push({
+            status: 'warn',
+            label: 'CC binary',
+            detail: `found at ${cc.path} but --version didn't parse — compat unchecked`,
+        });
+    }
+    else {
+        // CC not installed locally is the correct, intended state for containerized
+        // deploys and CI runners — dario uses the bundled scrubbed template (whose
+        // freshness is surfaced by the separate "Template" row below). Marking
+        // this WARN scared container users into thinking something was broken;
+        // it's INFO with a hint pointing at the install upside instead.
+        checks.push({
+            status: 'info',
+            label: 'CC binary',
+            detail: 'not installed locally — dario uses the bundled template. (Install @anthropic-ai/claude-code if you want auto-refresh from your own CC binary.)',
+        });
+    }
+    // ---- Template source
+    try {
+        checks.push({
+            status: CC_TEMPLATE._source === 'live' ? 'ok' : 'info',
+            label: 'Template',
+            detail: `${describeTemplate(CC_TEMPLATE)} (schema v${CC_TEMPLATE._schemaVersion ?? '?'})`,
+        });
+    }
+    catch (err) {
+        checks.push({ status: 'fail', label: 'Template', detail: `load failed: ${err.message}` });
+    }
+    // ---- Per-model prompt variants (dario#lock-step)
+    // CC ships several model families a different system prompt than the shared
+    // base. A template missing a family's variant silently serves that family
+    // the base prompt — a wire-fidelity degradation with no other symptom
+    // (requests still 200). Known causes: a bundle baked while variant capture
+    // failed, or a pre-variants live cache shadowing the bundle.
+    try {
+        const missing = missingVariantFamilies(CC_TEMPLATE);
+        if (missing.length === 0) {
+            checks.push({
+                status: 'ok',
+                label: 'Prompt variants',
+                detail: `all ${VARIANT_FAMILIES.length} model families carried (${VARIANT_FAMILIES.map((f) => f.key).join(', ')})`,
+            });
+        }
+        else {
+            checks.push({
+                status: 'warn',
+                label: 'Prompt variants',
+                detail: `missing: ${missing.join(', ')} — those models get the shared base prompt, not CC's model-specific one. Re-bake the template, or remove a pre-variants live cache (~/.dario/cc-template.live.json) and restart.`,
+            });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Prompt variants', detail: `check failed: ${err.message}` });
+    }
+    // ---- Per-request overhead surfacing.
+    // The CC system prompt + tool definitions are injected into every
+    // non-passthrough request and dominate the input-token cost on small
+    // turns. Anthropic caches them after the first hit (cache_creation
+    // tokens on call 1, then cache_read on subsequent calls within the
+    // 5-minute TTL), but non-CC users routing heavy tooling get
+    // surprised by the first-request charge. Surface the size up front
+    // so they can plan.
+    //
+    // No token estimate — char counts and tool count are factual; the
+    // tokenizer ratio varies enough between prose and tool-schema JSON
+    // (compressible structural keys) that any single divisor is
+    // misleading. Operators who want the exact number can read it off
+    // their first request's `cache_creation_input_tokens` once the proxy
+    // is warm. `--usage` adds the live snapshot for those who want it.
+    try {
+        const promptChars = CC_TEMPLATE.system_prompt?.length ?? 0;
+        const toolCount = (CC_TEMPLATE.tools ?? []).length;
+        const toolChars = JSON.stringify(CC_TEMPLATE.tools ?? []).length;
+        if (promptChars > 0 || toolCount > 0) {
+            checks.push({
+                status: 'info',
+                label: 'Overhead',
+                detail: `${promptChars.toLocaleString()} chars system prompt + ${toolCount} tool defs ` +
+                    `(${toolChars.toLocaleString()} chars JSON-serialized) injected per non-passthrough ` +
+                    `request. Cached after first hit; read-cost only on subsequent calls within ` +
+                    `the 5-minute TTL. Exact token count surfaces as cache_creation_input_tokens ` +
+                    `on the first response (or run \`dario doctor --usage\`).`,
+            });
+        }
+    }
+    catch { /* don't let overhead reporting break the doctor */ }
+    // ---- System-prompt mode (v3.34.0)
+    // Surfaces the configured `--system-prompt` mode + the resulting char
+    // count delta vs CC verbatim. Read-only — does not run a request.
+    // Env-only path here so doctor can be invoked without a live proxy.
+    try {
+        const rawMode = process.env['DARIO_SYSTEM_PROMPT'];
+        if (rawMode && rawMode !== 'verbatim') {
+            const cc = CC_TEMPLATE.system_prompt ?? '';
+            let resolved;
+            if (rawMode === 'partial' || rawMode === 'aggressive') {
+                resolved = resolveSystemPrompt(rawMode);
+            }
+            else {
+                // file-path mode — doctor doesn't read files (might leak path),
+                // just report that custom mode is active.
+                resolved = '';
+            }
+            const isCustom = rawMode !== 'partial' && rawMode !== 'aggressive';
+            const detail = isCustom
+                ? `DARIO_SYSTEM_PROMPT=${rawMode} (custom file). Runtime path replaces system[2].text with file contents.`
+                : `DARIO_SYSTEM_PROMPT=${rawMode}. Strips ${(cc.length - resolved.length).toLocaleString()} chars from CC's ${cc.length.toLocaleString()}-char prompt. ` +
+                    `See docs/research/system-prompt-classifier-study.md for the empirical validation that this slot is unfingerprinted by the billing classifier.`;
+            checks.push({ status: 'info', label: 'System-prompt mode', detail });
+        }
+    }
+    catch { /* never let prompt-mode reporting break the doctor */ }
+    // ---- Outbound proxy mode (v3.35.0)
+    // Surfaces whether `--upstream-proxy` / DARIO_UPSTREAM_PROXY is set.
+    // Doctor runs without a live proxy, so we read the env-var path only
+    // (the CLI flag's effect is in-process and not visible from doctor).
+    // Credentials in the URL are masked; only host:port is shown.
+    try {
+        const rawProxy = process.env['DARIO_UPSTREAM_PROXY'];
+        if (rawProxy && rawProxy.trim() !== '') {
+            let display = rawProxy;
+            try {
+                const u = new URL(rawProxy);
+                if (u.username)
+                    u.username = '***';
+                if (u.password)
+                    u.password = '***';
+                display = u.toString();
+            }
+            catch { /* leave raw if unparseable; CLI will error at startup */ }
+            checks.push({
+                status: 'info',
+                label: 'Outbound proxy',
+                detail: `DARIO_UPSTREAM_PROXY=${display}. Upstream fetches routed via this proxy; localhost calls bypass. Requires Bun runtime. See docs/vpn-routing.md.`,
+            });
+        }
+    }
+    catch { /* never let proxy reporting break the doctor */ }
+    // ---- Template drift
+    try {
+        const drift = detectDrift(CC_TEMPLATE);
+        const status = drift.installedVersion === null ? 'info' : drift.drifted ? 'warn' : 'ok';
+        checks.push({ status, label: 'Template drift', detail: drift.message });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Template drift', detail: `check failed: ${err.message}` });
+    }
+    void CURRENT_SCHEMA_VERSION; // keep the import load-bearing for future schema checks
+    // ---- OAuth
+    try {
+        const { getStatus } = await import('./oauth.js');
+        const s = await getStatus();
+        if (!s.authenticated) {
+            // What actually serves is the POOL, not the legacy credentials.json —
+            // so ask the pool before reporting an auth failure. See oauthCheckRow.
+            let poolHealthy = 0, poolTotal = 0;
+            try {
+                const { listAccountAliases, loadAllAccounts } = await import('./accounts.js');
+                if ((await listAccountAliases()).length > 0) {
+                    const loaded = await loadAllAccounts();
+                    const now = Date.now();
+                    poolTotal = loaded.length;
+                    poolHealthy = loaded.filter((a) => a.expiresAt > now).length;
+                }
+            }
+            catch { /* pool unreadable — oauthCheckRow falls back to the legacy verdict */ }
+            checks.push(oauthCheckRow({ legacyStatus: s.status, legacyCanRefresh: !!s.canRefresh, poolHealthy, poolTotal }));
+        }
+        else {
+            checks.push({ status: 'ok', label: 'OAuth', detail: `${s.status} (expires in ${s.expiresIn})` });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'OAuth', detail: `check failed: ${err.message}` });
+    }
+    // ---- Authorize-URL probe (opt-in, --probe).
+    // One GET to the authorize endpoint with dario's effective OAuth config.
+    // This is the single reliable signal for the class of bug that broke
+    // #42 / #71 — Anthropic flipping server-side scope policy without
+    // changing the CC binary. The nightly probe in check-cc-authorize-
+    // probe.mjs hits Cloudflare challenges from CI IPs; running from a
+    // user's machine bypasses that. No PII leaves: the probe uses a
+    // fresh PKCE challenge and a dummy redirect_uri, and only reads the
+    // status code / Location header / response body markers.
+    if (opts.probe) {
+        try {
+            const cfg = await detectCCOAuthConfig();
+            const result = await runAuthorizeProbe({
+                clientId: cfg.clientId,
+                authorizeUrl: cfg.authorizeUrl,
+                scopes: cfg.scopes,
+            });
+            const status = result.verdict === 'accepted'
+                ? 'ok'
+                : result.verdict === 'rejected'
+                    ? 'fail'
+                    : 'warn';
+            const label = 'Authorize probe';
+            const summary = `${result.scopeCount}-scope ${result.verdict} — ${result.reason}`;
+            checks.push({ status, label, detail: summary });
+            if (result.verdict !== 'accepted') {
+                // On rejection: the URL is the one `accounts add` would open —
+                // surface it so the user can paste and diff against `claude
+                // /login`'s URL. On inconclusive (often Cloudflare from our
+                // fetch-based probe — CF challenges non-browser clients
+                // regardless of IP): the same URL pasted into the user's
+                // browser bypasses CF since a real browser passes the
+                // challenge. Either way, the URL is the actionable artifact.
+                checks.push({ status: 'info', label: 'Probe URL', detail: result.probedUrl });
+            }
+        }
+        catch (err) {
+            checks.push({
+                status: 'warn',
+                label: 'Authorize probe',
+                detail: `check failed: ${err.message}`,
+            });
+        }
+    }
+    // ---- Usage snapshot (opt-in, --usage).
+    // Fires one `POST /v1/messages` via the loaded OAuth (Haiku, max_tokens=1)
+    // to capture the current rate-limit snapshot including the per-model
+    // buckets Anthropic started carving around 2026-04-25. Surfaces the
+    // `All models` vs `Sonnet only` split the way the user dashboard does.
+    // Direct-to-Anthropic, not through the proxy — the proxy doesn't need
+    // to be running for `dario doctor --usage`.
+    if (opts.usage) {
+        try {
+            const { parseRateLimits } = await import('./pool.js');
+            const { billingBucketFromClaim } = await import('./analytics.js');
+            // Probe routing decision: Anthropic's subscription path rejects
+            // non-CC-shaped requests on Sonnet/Opus (returns 429 with no
+            // rate-limit headers). Haiku accepts the raw shape. So:
+            //   - If a local `dario proxy` is listening, route through it —
+            //     the proxy injects the full CC template and all three families
+            //     succeed, giving us the _sonnet / _opus / _haiku per-model
+            //     bucket headers on a single round trip each.
+            //   - Else fall back to direct-to-Anthropic with Haiku only.
+            //     Unified buckets surface but per-model buckets won't.
+            const dario_base = process.env.DARIO_TEST_URL || 'http://127.0.0.1:3456';
+            // The proxy validates Authorization against DARIO_API_KEY when set.
+            // Fall back to literal 'dario' (the documented loopback-only default)
+            // when unset so local-dev probes against a no-auth proxy continue to
+            // work. Without reading the env here, `dario doctor --usage` 401s on
+            // every deploy that sets a real auth secret — which is every prod
+            // deploy that follows the README's "non-loopback bind" guidance.
+            const dario_auth = process.env.DARIO_API_KEY || 'dario';
+            let probeEndpoint = `${dario_base}/v1/messages`;
+            let probeHeaders = {
+                'content-type': 'application/json',
+                'anthropic-version': '2023-06-01',
+                'authorization': `Bearer ${dario_auth}`,
+            };
+            let proxyAvailable = false;
+            try {
+                const healthRes = await fetch(`${dario_base}/health`, { signal: AbortSignal.timeout(800) });
+                proxyAvailable = healthRes.ok;
+            }
+            catch { /* proxy not running */ }
+            if (!proxyAvailable) {
+                const { getAccessToken } = await import('./oauth.js');
+                const token = await getAccessToken();
+                probeEndpoint = 'https://api.anthropic.com/v1/messages';
+                probeHeaders = {
+                    'content-type': 'application/json',
+                    'anthropic-version': '2023-06-01',
+                    'anthropic-beta': 'oauth-2025-04-20',
+                    'authorization': `Bearer ${token}`,
+                };
+                checks.push({
+                    status: 'info',
+                    label: 'Usage probe',
+                    detail: 'dario proxy not running — probing direct. Per-model buckets visible only when probing through a running proxy (start `dario proxy` in another terminal and re-run).',
+                });
+            }
+            // Probe each family in parallel. Anthropic only returns the
+            // per-model 7d bucket header on a request TO that family.
+            const probe = async (model) => {
+                const res = await fetch(probeEndpoint, {
+                    method: 'POST',
+                    headers: probeHeaders,
+                    body: JSON.stringify({
+                        model,
+                        max_tokens: 1,
+                        messages: [{ role: 'user', content: 'ok' }],
+                    }),
+                    signal: AbortSignal.timeout(15_000),
+                });
+                // Consume the body so the socket releases; we only care about headers.
+                await res.text().catch(() => '');
+                // Ignore 429/4xx snapshots without useful rate-limit headers.
+                if (!res.headers.get('anthropic-ratelimit-unified-status'))
+                    return null;
+                return parseRateLimits(res.headers);
+            };
+            const results = await Promise.all(PROBE_FAMILIES.map(f => probe(f.model).catch(() => null)));
+            // Use the first non-null snapshot for the unified view — they
+            // should all agree on the unified buckets (same account, same moment).
+            const firstOk = results.find(s => s !== null);
+            if (!firstOk)
+                throw new Error('all probe requests failed');
+            const bucket = billingBucketFromClaim(firstOk.claim);
+            const pct = (n) => `${(n * 100).toFixed(1)}%`;
+            let reset5hStr = '';
+            let reset7dStr = '';
+            if (firstOk.reset > 0) {
+                const relativeReset = formatReset(firstOk.reset, Date.now());
+                if (firstOk.claim.startsWith('five_hour')) {
+                    reset5hStr = `  •  resets in ${relativeReset}`;
+                }
+                else if (firstOk.claim.startsWith('seven_day')) {
+                    reset7dStr = `  •  resets in ${relativeReset}`;
+                }
+            }
+            checks.push({
+                status: firstOk.util5h >= 0.90 ? 'warn' : 'ok',
+                label: 'Usage 5h (all)',
+                detail: `${pct(firstOk.util5h)} used  •  status=${firstOk.status}${reset5hStr}  •  claim=${firstOk.claim} (${bucket})`,
+            });
+            checks.push({
+                status: firstOk.util7d >= 0.90 ? 'warn' : 'ok',
+                label: 'Usage 7d (all)',
+                detail: `${pct(firstOk.util7d)} used${reset7dStr}`,
+            });
+            // Merge per-model buckets across all probes — each probe's response
+            // carries at most its own family bucket; union them for display.
+            const mergedPerModel = {};
+            for (const s of results) {
+                if (!s)
+                    continue;
+                for (const [family, util] of Object.entries(s.perModel7d)) {
+                    mergedPerModel[family] = util;
+                }
+            }
+            for (const [family, util] of Object.entries(mergedPerModel).sort()) {
+                const divergence = util - firstOk.util7d;
+                const marker = Math.abs(divergence) > 0.05
+                    ? `  •  Δ vs 7d(all): ${divergence >= 0 ? '+' : ''}${(divergence * 100).toFixed(1)}pp`
+                    : '';
+                checks.push({
+                    status: util >= 0.90 ? 'warn' : 'ok',
+                    label: `Usage 7d (${family} only)`,
+                    detail: `${pct(util)} used${marker}`,
+                });
+            }
+            if (firstOk.overageUtil > 0) {
+                checks.push({
+                    status: firstOk.overageUtil >= 0.90 ? 'warn' : 'info',
+                    label: 'Usage overage',
+                    detail: `${pct(firstOk.overageUtil)} of configured monthly spend`,
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                status: 'warn',
+                label: 'Usage snapshot',
+                detail: `probe failed: ${err.message}`,
+            });
+        }
+    }
+    // ---- Client-system obedience probe (opt-in, --obedience).
+    // dario#509 / the 2026-06-12 deepdive planner outage: Anthropic's serving
+    // side changed how claude-sonnet-4-6 weighed client system text merged
+    // after the CC persona in block 3 — wire bytes identical, every existing
+    // check green — and the only symptom was a downstream consumer failing to
+    // get the JSON its system prompt demanded. This probe asserts the property
+    // those checks miss: a model, reached THROUGH the proxy's template merge,
+    // actually follows a client-supplied system instruction.
+    //
+    // Per family: up to 3 attempts (tolerates sampling), pass on the first
+    // obedient reply. Families probe in parallel, so worst-case wall time is
+    // bounded by attempts × timeout, not by family count.
+    //
+    // Requires a running proxy: a direct-to-Anthropic raw client shape would
+    // not exercise the cc-template merge seam (and Sonnet/Opus reject non-CC
+    // shapes on the subscription path anyway).
+    //
+    // Verdict semantics (consumed by scripts/check-doctor-drift.mjs):
+    //   fail = the model ANSWERED but ignored the instruction. Behavioral and
+    //          upstream-influenced — investigate the system-prompt
+    //          presentation/merge (CLIENT_SYSTEM_PREFACE, block-3 structure),
+    //          NOT necessarily a dario bug, and don't start with version
+    //          bisects (the 2026-06-12 incident burned hours on those; they
+    //          were all negative because nothing on dario's side changed).
+    //   warn = the probe never got an answer (network/429/5xx) — infra
+    //          flake, not drift.
+    if (opts.obedience) {
+        const dario_base = process.env.DARIO_TEST_URL || 'http://127.0.0.1:3456';
+        // Same auth fallback as the --usage probe: the proxy validates
+        // Authorization against DARIO_API_KEY when set; literal 'dario' is the
+        // documented loopback-only default for no-auth local proxies.
+        const dario_auth = process.env.DARIO_API_KEY || 'dario';
+        let proxyUp = false;
+        try {
+            const healthRes = await fetch(`${dario_base}/health`, { signal: AbortSignal.timeout(800) });
+            proxyUp = healthRes.ok;
+        }
+        catch { /* proxy not running */ }
+        if (!proxyUp) {
+            checks.push({
+                status: 'info',
+                label: 'Obedience',
+                detail: 'dario proxy not running — skipped. The probe must route through the proxy to exercise the client-system merge; start `dario proxy` and re-run.',
+            });
+        }
+        else {
+            const ATTEMPTS = 3;
+            const probeFamily = async ({ family, model }) => {
+                let lastReply = '';
+                let lastErr = null;
+                for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+                    try {
+                        const res = await fetch(`${dario_base}/v1/messages`, {
+                            method: 'POST',
+                            headers: {
+                                'content-type': 'application/json',
+                                'anthropic-version': '2023-06-01',
+                                'authorization': `Bearer ${dario_auth}`,
+                            },
+                            body: JSON.stringify({
+                                model,
+                                max_tokens: 64,
+                                system: OBEDIENCE_SYSTEM_PROMPT,
+                                messages: [{ role: 'user', content: 'ping' }],
+                            }),
+                            signal: AbortSignal.timeout(30_000),
+                        });
+                        if (!res.ok) {
+                            await res.text().catch(() => '');
+                            lastErr = `HTTP ${res.status}`;
+                            continue;
+                        }
+                        const body = await res.json().catch(() => null);
+                        const text = extractMessageText(body);
+                        if (isObedientReply(text)) {
+                            return {
+                                status: 'ok',
+                                label: `Obedience (${family})`,
+                                detail: `"${text}" (attempt ${attempt}/${ATTEMPTS})`,
+                            };
+                        }
+                        // A completed-but-disobedient reply (including a refusal's
+                        // empty content) is the drift signal — remember it so it
+                        // dominates over any later transport error.
+                        lastReply = text;
+                        lastErr = null;
+                    }
+                    catch (err) {
+                        lastErr = err.message;
+                    }
+                }
+                if (lastErr !== null && lastReply === '') {
+                    return {
+                        status: 'warn',
+                        label: `Obedience (${family})`,
+                        detail: `probe could not complete (${lastErr}) — infra flake, not behavioral drift`,
+                    };
+                }
+                return {
+                    status: 'fail',
+                    label: `Obedience (${family})`,
+                    detail: `model answered but ignored the client system prompt (last reply: "${lastReply.slice(0, 80)}") — behavioral, upstream-influenced; investigate presentation/merge (CLIENT_SYSTEM_PREFACE seam), not necessarily a dario bug`,
+                };
+            };
+            const rows = await Promise.all(PROBE_FAMILIES.map((f) => probeFamily(f)));
+            checks.push(...rows);
+        }
+    }
+    // ---- Account pool
+    try {
+        const { listAccountAliases, loadAllAccounts } = await import('./accounts.js');
+        const aliases = await listAccountAliases();
+        if (aliases.length === 0) {
+            // Pool-as-primitive (v5.0): no accounts/ entries. Either not logged in,
+            // or a pre-v5 `dario login` whose credentials.json hasn't been back-filled
+            // into the pool yet — that happens on the next `dario login` / `dario proxy`.
+            const { loadCredentials } = await import('./oauth.js');
+            const creds = await loadCredentials();
+            if (creds?.claudeAiOauth?.accessToken) {
+                checks.push({ status: 'info', label: 'Pool', detail: 'pool of 1 (login credentials present, not yet materialized — runs on next `dario login` or `dario proxy`); `dario accounts add <alias>` adds more for headroom routing' });
+            }
+            else {
+                checks.push({ status: 'info', label: 'Pool', detail: 'empty — run `dario login` (a pool of one) or `dario accounts add <alias>`' });
+            }
+        }
+        else {
+            const loaded = await loadAllAccounts();
+            const now = Date.now();
+            const expired = loaded.filter((a) => a.expiresAt <= now).length;
+            checks.push({
+                status: expired > 0 ? 'warn' : 'ok',
+                label: 'Pool',
+                detail: `pool of ${aliases.length}` +
+                    (expired > 0 ? `, ${expired} expired` : '') +
+                    (aliases.length === 1 ? ' (a pool of one — `dario accounts add <alias>` to load-balance)' : ''),
+            });
+            // Next-account-in-rotation surfacing. The proxy's per-request
+            // selector picks by max headroom (with 7d_<family> per-model
+            // bucket considered when a request's model family is known);
+            // doctor doesn't know the next request's model so it reports
+            // the family-agnostic pick. That's still the right preview for
+            // operators wondering "if I send a request right now, which
+            // account gets it?" — it matches `pool.select()` with no family
+            // hint, the same call the proxy uses when no model is parsed
+            // yet (e.g. on misshapen requests). Shown for a pool of one too
+            // (v5.0): it confirms the sole account is eligible, not rejected.
+            if (aliases.length >= 1) {
+                try {
+                    const { AccountPool } = await import('./pool.js');
+                    const pool = new AccountPool();
+                    for (const acc of loaded) {
+                        pool.add(acc.alias, {
+                            accessToken: acc.accessToken,
+                            refreshToken: acc.refreshToken,
+                            expiresAt: acc.expiresAt,
+                            deviceId: acc.deviceId,
+                            accountUuid: acc.accountUuid,
+                        });
+                    }
+                    const next = pool.select();
+                    const ps = pool.status();
+                    checks.push({
+                        status: 'info',
+                        label: 'Pool routing',
+                        detail: next
+                            ? `next: ${next.alias}  (max-headroom select; ${ps.healthy}/${ps.accounts} healthy)`
+                            : `no eligible account — all rejected or near-expiry (${ps.exhausted}/${ps.accounts} exhausted)`,
+                    });
+                }
+                catch (err) {
+                    checks.push({ status: 'warn', label: 'Pool routing', detail: `check failed: ${err.message}` });
+                }
+            }
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Pool', detail: `check failed: ${err.message}` });
+    }
+    // ---- Live session state (only observable from a running proxy)
+    // Session/sticky counts live in the proxy's memory, so — unlike the
+    // local-state checks above — this reads them off /health (internal-disclosure
+    // caller, so it must reach dario on loopback). Silent skip when no proxy is
+    // up: the counts don't exist, and doctor is often run because it's down.
+    try {
+        const darioBase = process.env.DARIO_TEST_URL || 'http://127.0.0.1:3456';
+        const healthRes = await fetch(`${darioBase}/health`, { signal: AbortSignal.timeout(800) });
+        if (healthRes.ok) {
+            const health = (await healthRes.json().catch(() => null));
+            const sx = health?.sessions;
+            if (sx && typeof sx.mode === 'string') {
+                const detail = sx.mode === 'pool'
+                    ? `${sx.stickyBindings ?? 0} sticky binding${sx.stickyBindings === 1 ? '' : 's'} — conversation→account affinity, lazily reaped (6h idle TTL, cap 2000)`
+                    : `${sx.active ?? 0} active session id${sx.active === 1 ? '' : 's'} — lazily reaped (LRU cap 1024, no background sweeper)`;
+                checks.push({ status: 'info', label: 'Sessions', detail });
+            }
+        }
+    }
+    catch { /* proxy not running — live session state unavailable, skip */ }
+    // ---- Identity drift (pool account snapshot vs live ~/.claude.json)
+    try {
+        const { detectClaudeIdentity, listAccountAliases, loadAllAccounts } = await import('./accounts.js');
+        const live = await detectClaudeIdentity();
+        const aliases = await listAccountAliases();
+        const loaded = aliases.length ? await loadAllAccounts() : [];
+        const driftChecks = checkIdentityDrift({
+            live,
+            poolAccounts: loaded.map((a) => ({
+                alias: a.alias,
+                deviceId: a.deviceId,
+                accountUuid: a.accountUuid,
+            })),
+        });
+        for (const c of driftChecks)
+            checks.push(c);
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Identity', detail: `check failed: ${err.message}` });
+    }
+    // ---- Secondary backends
+    try {
+        const { listBackends } = await import('./openai-backend.js');
+        const backends = await listBackends();
+        checks.push({
+            status: 'info',
+            label: 'Backends',
+            detail: backends.length === 0
+                ? 'none configured (Claude subscription is the only route)'
+                : `${backends.length} configured: ${backends.map((b) => b.name).join(', ')}`,
+        });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Backends', detail: `check failed: ${err.message}` });
+    }
+    // ---- Failover readiness (v6.0.0) — see failoverReadiness() for the why.
+    try {
+        const { loadConfig } = await import('./config-file.js');
+        const { listCodexAccountAliases } = await import('./codex-accounts.js');
+        const { listBackends } = await import('./openai-backend.js');
+        const cfg = loadConfig().config;
+        const raw = (process.env.DARIO_POOL_FALLBACK ?? cfg.poolFallback?.model ?? '').trim();
+        const chain = raw.split(',').map((m) => m.trim()).filter(Boolean);
+        const codexAliases = await listCodexAccountAliases().catch(() => []);
+        const backends = await listBackends().catch(() => []);
+        const verdict = failoverReadiness({
+            chain,
+            codexAccounts: codexAliases.length,
+            backends: backends.map((b) => b.name),
+        });
+        checks.push({ status: verdict.status, label: 'Failover', detail: verdict.detail });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Failover', detail: `check failed: ${err.message}` });
+    }
+    // ---- CC sub-agent (v3.26, direction #2)
+    try {
+        const { loadSubagentStatus } = await import('./subagent.js');
+        const s = loadSubagentStatus();
+        if (!s.agentsDirExists) {
+            checks.push({ status: 'info', label: 'Sub-agent', detail: 'not installed (~/.claude/agents missing — Claude Code not installed?)' });
+        }
+        else if (!s.installed) {
+            checks.push({ status: 'info', label: 'Sub-agent', detail: 'not installed — run `dario subagent install` to enable CC integration' });
+        }
+        else if (!s.current) {
+            checks.push({
+                status: 'warn',
+                label: 'Sub-agent',
+                detail: `installed v${s.fileVersion ?? 'unknown'}, does not match this dario — run \`dario subagent install\` to refresh`,
+            });
+        }
+        else {
+            checks.push({ status: 'ok', label: 'Sub-agent', detail: `installed v${s.fileVersion} at ${s.path}` });
+        }
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Sub-agent', detail: `check failed: ${err.message}` });
+    }
+    // ---- ~/.dario dir
+    try {
+        const home = join(homedir(), '.dario');
+        checks.push({ status: 'info', label: 'Home', detail: home });
+    }
+    catch {
+        // never fails in practice — homedir() is always defined on supported platforms
+    }
+    return checks;
+}
+function nodeStatus() {
+    const m = /^v(\d+)\./.exec(process.version);
+    const major = m ? parseInt(m[1], 10) : 0;
+    // engines: >=18 (see package.json). 18/20 are current supported Node LTS
+    // lines — anything below 18 fails; above is ok.
+    if (major >= 18)
+        return 'ok';
+    if (major === 0)
+        return 'warn';
+    return 'fail';
+}
+function safely(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+// Exported for unit tests.
+export function redactSecret(value) {
+    if (value.length <= 8)
+        return `<${value.length} chars>`;
+    return `${value.slice(0, 4)}…${value.slice(-4)} (length ${value.length})`;
+}
+// Exported for unit tests. Pure — takes the two headers + the expected
+// key, returns the classification. Separated from the HTTP dance so
+// tests can drive synthetic inputs without binding a socket.
+export function classifyAuthHeaders(headers, expected) {
+    const xRaw = headers['x-api-key'];
+    const aRaw = headers['authorization'];
+    const xVal = Array.isArray(xRaw) ? xRaw[0] : xRaw;
+    const aVal = Array.isArray(aRaw) ? aRaw[0] : aRaw;
+    const xApiKey = { present: xVal !== undefined };
+    if (xVal !== undefined) {
+        xApiKey.length = xVal.length;
+        xApiKey.redacted = redactSecret(xVal);
+        xApiKey.matches = xVal === expected;
+    }
+    const authorization = { present: aVal !== undefined };
+    if (aVal !== undefined) {
+        authorization.length = aVal.length;
+        authorization.bearerPrefix = /^Bearer\s+/i.test(aVal);
+        const stripped = aVal.replace(/^Bearer\s+/i, '');
+        authorization.redacted = redactSecret(stripped);
+        authorization.matches = stripped === expected;
+    }
+    let verdict;
+    if (!xApiKey.present && !authorization.present) {
+        verdict = 'no-auth-header';
+    }
+    else if (xApiKey.matches === true || authorization.matches === true) {
+        verdict = 'match';
+    }
+    else {
+        verdict = 'mismatch';
+    }
+    return { xApiKey, authorization, verdict };
+}
+function diagnoseAuthCheck(result) {
+    switch (result.verdict) {
+        case 'match':
+            return `client auth matches DARIO_API_KEY. A real dario proxy would accept this request.`;
+        case 'mismatch': {
+            const parts = [];
+            if (result.authorization?.present) {
+                const bearer = result.authorization.bearerPrefix ? ' (Bearer prefix present)' : ' (Bearer prefix missing)';
+                parts.push(`Authorization header${bearer}: value ${result.authorization.redacted} — does NOT match expected ${redactSecret(result.expected)}.`);
+            }
+            if (result.xApiKey?.present) {
+                parts.push(`x-api-key header: value ${result.xApiKey.redacted} — does NOT match expected ${redactSecret(result.expected)}.`);
+            }
+            const hint = suggestAuthFix(result);
+            return parts.join(' ') + (hint ? ' ' + hint : '');
+        }
+        case 'no-auth-header':
+            return (`client sent no x-api-key and no Authorization header. ` +
+                `Expected ${redactSecret(result.expected)} in either. ` +
+                `Set ANTHROPIC_API_KEY=${result.expected} in your client's environment, ` +
+                `or use your tool's own "API key" config field if it has one.`);
+        case 'timeout':
+            return (`no request received within the timeout. Did your client target the ` +
+                `port printed above? If the client uses a base URL you configured ` +
+                `elsewhere, point it at the --auth-check listener for this one request.`);
+        case 'no-enforcement':
+            return (`DARIO_API_KEY is not set — dario does not enforce auth on loopback ` +
+                `by default, so any request would be allowed through. To test auth ` +
+                `enforcement, set DARIO_API_KEY=your-secret before running --auth-check.`);
+    }
+}
+/** Pattern-match common failure modes for a sharper hint. */
+function suggestAuthFix(result) {
+    const auth = result.authorization;
+    const exp = result.expected;
+    // Authorization value looks like a real Anthropic key — very common
+    // pattern: client has one stashed from an earlier setup (OpenClaw's
+    // auth-profiles.json, ANTHROPIC_API_KEY env, config file) and it's
+    // shadowing the intended "dario" value. dario#97 exactly.
+    if (auth?.present && auth.redacted?.startsWith('sk-a')) {
+        return (`The value your client sent looks like a real Anthropic API key ` +
+            `(starts with "sk-a…"). Your client has that key configured somewhere ` +
+            `(auth-profiles.json, ANTHROPIC_API_KEY env, client config file) and it's ` +
+            `overriding "${exp}". Either replace it with "${exp}" or bypass auth entirely ` +
+            `by running dario on --host=127.0.0.1 without DARIO_API_KEY set.`);
+    }
+    // Authorization with no "Bearer " prefix: some clients just set the
+    // header value raw.
+    if (auth?.present && auth.bearerPrefix === false) {
+        return (`The Authorization header is missing the "Bearer " prefix. Most ` +
+            `HTTP client libraries want "Bearer <key>" as one value — yours seems ` +
+            `to be setting the key directly. Check your client's auth config.`);
+    }
+    return null;
+}
+/**
+ * Listen for one inbound request on a random loopback port, classify
+ * whatever auth headers it carries against `DARIO_API_KEY`, return a
+ * structured result. Sends 200 / 401 to the inbound request so the
+ * client doesn't hang, then closes. This is a probe — it does not
+ * proxy, does not log, does not persist.
+ */
+export async function runAuthCheck(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    const expected = opts.expectedKey ?? process.env.DARIO_API_KEY ?? '';
+    if (!expected) {
+        return {
+            received: false,
+            expected: '<unset>',
+            verdict: 'no-enforcement',
+            diagnosis: diagnoseAuthCheck({ received: false, expected: '<unset>', verdict: 'no-enforcement' }),
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            server.close(() => resolve(result));
+        };
+        const server = createServer((req, res) => {
+            const { xApiKey, authorization, verdict } = classifyAuthHeaders(req.headers, expected);
+            const port = server.address()?.port;
+            const result = {
+                received: true,
+                port,
+                expected,
+                xApiKey,
+                authorization,
+                verdict,
+                diagnosis: '',
+            };
+            result.diagnosis = diagnoseAuthCheck(result);
+            res.writeHead(verdict === 'match' ? 200 : 401, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                message: 'dario auth-check received this request — see the dario CLI output for the diagnostic.',
+                verdict,
+            }));
+            settle(result);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const port = server.address().port;
+            opts.onListening?.(port);
+        });
+        setTimeout(() => {
+            const port = server.address()?.port;
+            settle({
+                received: false,
+                port,
+                expected,
+                verdict: 'timeout',
+                diagnosis: diagnoseAuthCheck({ received: false, port, expected, verdict: 'timeout' }),
+            });
+        }, timeoutMs);
+    });
+}