@nac3/forge-cli 1.20.1 → 1.21.0

package/dist/commands/doctor.js

@@ -1,14 +1,31 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { c, header } from '../ui/colors.js';
-import { loadLicense, configDir } from '../license/index.js';
+import { peekLicense, configDir } from '../license/index.js';
 import { VERSION } from '../version.js';
 import { Vault } from '../vault/store.js';
+import { parseBrainConfig, defaultBrainConfig, vaultSlotForProvider, } from '../core/brain_config.js';
+import { probeKeysReadOnly } from '../core/provider_keys.js';
+import { VOICE_CREDENTIAL_SOURCES } from '../voice/registry.js';
+import { DEFAULT_VOICE_CONFIG } from '../voice/types.js';
+function mk(check) {
+    return { ...check, ok: check.status === 'ok' };
+}
+/** The one place that phrases the third state, so it reads the same
+ *  everywhere and a test can assert on it. */
+function couldNotVerify(what, why) {
+    return 'could not verify ' + what + ': ' + why;
+}
+function firstLine(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return (msg.split('\n')[0] ?? 'unknown error').slice(0, 160);
+}
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
         .description('Check the local environment + Forge installation + vault + voice + reader deps.')
         .option('--json', 'emit JSON instead of human-readable output')
+        .option('--verbose', 'show, for every check, which source it read and what it expected vs found')
         .action(async (opts) => {
         const checks = await runDoctorChecks();
         if (opts.json) {
@@ -20,20 +37,39 @@ export function registerDoctorCommand(program) {
         console.log('  Forge CLI ' + c.dim(VERSION));
         console.log('');
         for (const check of checks) {
-            const mark = check.ok ? c.success('✓') : c.warn('✗');
+            const mark = check.status === 'ok' ? c.success('+')
+                : check.status === 'fail' ? c.warn('x')
+                    : c.dim('?');
             console.log('  ' + mark + ' ' + check.name + c.dim(' -- ' + check.detail));
-            if (!check.ok && check.hint) {
-                console.log('    ' + c.dim('hint: ' + check.hint));
+            if (opts.verbose) {
+                console.log('    ' + c.dim('source:   ' + check.source));
+                if (check.expected)
+                    console.log('    ' + c.dim('expected: ' + check.expected));
+                if (check.found)
+                    console.log('    ' + c.dim('found:    ' + check.found));
+            }
+            if (check.conflict) {
+                console.log('    ' + c.dim('also:     ' + check.conflict));
+            }
+            if (check.status !== 'ok' && check.hint) {
+                console.log('    ' + c.dim('hint:     ' + check.hint));
             }
         }
         console.log('');
-        const failing = checks.filter((ch) => !ch.ok).length;
-        if (failing === 0) {
+        const failing = checks.filter((ch) => ch.status === 'fail').length;
+        const unknown = checks.filter((ch) => ch.status === 'unknown').length;
+        const verified = checks.length - failing - unknown;
+        console.log('  ' + verified + ' verified / ' + failing + ' failing / '
+            + unknown + ' could not verify  (' + checks.length + ' checks)');
+        if (failing === 0 && unknown === 0) {
             console.log(c.success('All checks passed.'));
         }
-        else {
+        else if (failing > 0) {
             console.log(c.warn(failing + ' check(s) need attention.'));
         }
+        if (unknown > 0 && !opts.verbose) {
+            console.log(c.dim('  run `yf doctor --verbose` to see which source each check read.'));
+        }
         /* PND-135 -- passive (cached) update notice. Best-effort; never blocks. */
         try {
             const { checkForUpdate } = await import('../core/self_update.js');
@@ -48,340 +84,634 @@ export function registerDoctorCommand(program) {
         catch { /* never block doctor on the update check */ }
     });
 }
-async function runDoctorChecks() {
+export async function runDoctorChecks(env = {}) {
+    const dir = env.configDir ?? configDir();
+    const cwd = env.cwd ?? process.cwd();
     const checks = [];
-    /* 1. Node.js version. */
+    await checkNode(checks);
+    await checkLicenseState(checks, dir);
+    await runHito4DoctorChecks(checks, {
+        ...(env.fetchImpl ? { fetchImpl: env.fetchImpl } : {}),
+        ...(env.nowMs ? { nowMs: env.nowMs } : {}),
+        ...(env.timeoutMs !== undefined ? { timeoutMs: env.timeoutMs } : {}),
+        configDir: dir,
+    });
+    /* ONE read-only probe of the key material, shared by the vault,
+     * voice, brain and github checks. They all have to agree, and they
+     * all have to be able to say "I could not read the vault". */
+    const keys = await probeKeysReadOnly({ configDir: dir });
+    await checkCredentialsVault(checks, keys);
+    await checkVoiceProviders(checks, dir, keys);
+    await checkBrainProvider(checks, dir, keys);
+    await checkGithubToken(checks, keys);
+    await checkI18nCatalogs(checks);
+    await checkHardcodedStrings(checks);
+    await checkUserManuals(checks);
+    await checkReaderDeps(checks);
+    checkRecapMode(checks);
+    await checkProjectRoot(checks, cwd);
+    return checks;
+}
+/* ------------------------------------------------------------------ */
+/* 1. Node                                                             */
+/* ------------------------------------------------------------------ */
+async function checkNode(checks) {
     const nodeMajor = parseInt(process.versions.node.split('.')[0] ?? '0', 10);
-    checks.push({
+    checks.push(mk({
+        id: 'node_version',
         name: 'Node.js >= 18.17',
-        ok: nodeMajor >= 18,
+        status: nodeMajor >= 18 ? 'ok' : 'fail',
+        source: 'process.versions.node (the runtime executing this command)',
+        expected: 'major >= 18',
+        found: process.versions.node,
         detail: 'detected ' + process.versions.node,
         ...(nodeMajor < 18 ? { hint: 'install Node 18.17 or newer from nodejs.org' } : {}),
-    });
-    /* 2. License state. */
-    const lic = await loadLicense();
-    checks.push({
-        name: 'License state',
-        ok: lic.status === 'paid' || lic.status === 'trial',
-        detail: 'status=' + lic.status + ' (' + lic.source + ')',
-        ...(lic.status === 'expired' ? { hint: 'run `yf license activate` with your seat token' } : {}),
-    });
-    /* 2b. HITO 4 worker checks (PND-031, F104 + license caching).
-     *      Three small probes that surface common HITO 4 mis-configs
-     *      before the user hits them mid-chat:
-     *        (a) prompts.yujin.app reachable -- HTTPS HEAD with a short
-     *            timeout. Surfaces DNS / outage / firewall.
-     *        (b) yujin_license slot configured -- Vault.has() so the
-     *            HMAC bearer construction does not throw mid-call.
-     *        (c) license cached < 24h -- mtime of license.json compared
-     *            to now. The local cache is the canonical source for
-     *            offline use; if it is stale, schedule `yf license sync`. */
-    await runHito4DoctorChecks(checks);
-    /* 3. Vault (HITO 0). The vault file may not exist if the
-       user has never opened the chat panel; that is NOT a
-       failure, just informational. */
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 2. License state -- READ ONLY (PND-188)                             */
+/* ------------------------------------------------------------------ */
+async function checkLicenseState(checks, dir) {
+    const src = path.join(dir, 'license.json') + ' then ' + path.join(dir, 'trial.json');
+    let state;
     try {
-        const v = await Vault.open({ configDir: configDir() });
-        const slotNames = v.list().map((s) => s.name);
-        checks.push({
-            name: 'Credentials vault',
-            ok: true,
-            detail: slotNames.length + ' slot(s) configured: ' + (slotNames.join(', ') || '(empty)'),
-        });
+        state = await peekLicense();
     }
     catch (err) {
-        /* Vault not yet initialised is the expected state for a
-           fresh install. The chat panel creates it lazily. */
-        checks.push({
+        checks.push(mk({
+            id: 'license_state',
+            name: 'License state',
+            status: 'unknown',
+            source: src,
+            expected: 'a parseable license.json or trial.json',
+            found: 'a file that exists but could not be parsed',
+            detail: couldNotVerify('the license state', firstLine(err)),
+            hint: 'inspect ' + path.join(dir, 'trial.json') + ' -- delete it to re-seed the trial',
+        }));
+        return;
+    }
+    if (state === null) {
+        /* Verified: nothing on disk. The trial starts on the first command
+         * that needs a license -- and `yf doctor` is deliberately NOT one
+         * of them, so this stays true after the command returns. */
+        checks.push(mk({
+            id: 'license_state',
+            name: 'License state',
+            status: 'ok',
+            source: src,
+            expected: 'license.json (paid seat) or trial.json (trial clock)',
+            found: 'neither -- nothing issued on this machine yet',
+            detail: 'no license yet; the 30-day trial starts on the first command that needs one '
+                + '(doctor does not start it)',
+        }));
+        return;
+    }
+    const good = state.status === 'paid' || state.status === 'trial';
+    checks.push(mk({
+        id: 'license_state',
+        name: 'License state',
+        status: good ? 'ok' : 'fail',
+        source: state.status === 'paid' ? path.join(dir, 'license.json') : path.join(dir, 'trial.json'),
+        expected: 'status paid or trial',
+        found: 'status=' + state.status
+            + (state.trial ? ' (' + state.trial.daysLeft + ' day(s) left)' : ''),
+        detail: 'status=' + state.status + ' (' + state.source + ')',
+        ...(good ? {} : { hint: 'run `yf license activate` with your seat token' }),
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 3. Credentials vault                                                */
+/* ------------------------------------------------------------------ */
+async function checkCredentialsVault(checks, keys) {
+    const src = path.join(keys.config_dir, 'vault.json');
+    if (!keys.vault_present) {
+        checks.push(mk({
+            id: 'credentials_vault',
+            name: 'Credentials vault',
+            status: 'ok',
+            source: src,
+            expected: 'an encrypted vault file',
+            found: 'absent',
+            detail: 'not yet initialised (created when you set the first slot)',
+        }));
+        return;
+    }
+    if (!keys.vault_readable) {
+        /* The old code answered `ok: true` from this very catch -- a green
+         * emitted from the branch that proves it could not look (PND-186). */
+        checks.push(mk({
+            id: 'credentials_vault',
             name: 'Credentials vault',
-            ok: true,
-            detail: 'not yet initialised (will be created when you set the first slot)',
-        });
-    }
-    /* 4. Voice provider keys (BYOK).
-     *
-     *  Two sources to consider (in priority order):
-     *    a) ~/.yujin-forge/provider_keys.json -- the new location
-     *       written by `yf voice setup` (encrypted blob synced
-     *       across devices via /v1/keys-sync).
-     *    b) Vault slots `openai` / `google_voice` / `elevenlabs`
-     *       -- legacy slots from the panel-based flow, still
-     *       respected for back-compat. */
-    let vaultSlotNames = [];
+            status: 'unknown',
+            source: src,
+            expected: 'a vault that opens with this machine fingerprint',
+            found: 'present but could not be opened',
+            detail: couldNotVerify('the vault contents', keys.vault_error ?? 'unknown error'),
+            hint: 'the vault is bound to the machine fingerprint; if you moved the file between '
+                + 'machines or users, re-set the slots with `yf keys setup`',
+        }));
+        return;
+    }
+    checks.push(mk({
+        id: 'credentials_vault',
+        name: 'Credentials vault',
+        status: 'ok',
+        source: src,
+        expected: 'a vault that opens with this machine fingerprint',
+        found: keys.vault_slots.length + ' slot(s)',
+        detail: keys.vault_slots.length + ' slot(s) configured: '
+            + (keys.vault_slots.join(', ') || '(empty)'),
+    }));
+}
+function voiceReady(kind, id, keys) {
+    const src = VOICE_CREDENTIAL_SOURCES[kind][id];
+    if (!src)
+        return false;
+    for (const slot of src.byok)
+        if (keys.status[slot])
+            return true;
+    return keys.vault_slots.includes(src.vault_slot);
+}
+function resolveVoice(kind, configured, keys) {
+    const candidates = Object.keys(VOICE_CREDENTIAL_SOURCES[kind]);
+    const configuredReady = voiceReady(kind, configured, keys);
+    let resolved = configuredReady ? configured : null;
+    if (resolved === null) {
+        /* Mirrors VoiceRouter.resolveReadyProvider: configured first, then
+         * the rest of the registry in insertion order. */
+        for (const id of candidates) {
+            if (id === configured)
+                continue;
+            if (voiceReady(kind, id, keys)) {
+                resolved = id;
+                break;
+            }
+        }
+    }
+    return { configured, configuredReady, resolved, candidates };
+}
+async function checkVoiceProviders(checks, dir, keys) {
+    const file = path.join(dir, 'voice-config.json');
+    const id = 'voice_providers';
+    const name = 'Voice providers (STT + TTS)';
+    if (!keys.vault_readable) {
+        checks.push(mk({
+            id, name, status: 'unknown',
+            source: file + ' + ' + path.join(dir, 'vault.json'),
+            expected: 'the configured providers and their credentials',
+            found: 'the vault could not be opened, so provider readiness is unknowable',
+            detail: couldNotVerify('voice provider readiness', keys.vault_error ?? 'vault unreadable'),
+        }));
+        return;
+    }
+    let cfg;
+    let seeded = false;
     try {
-        const v = await Vault.open({ configDir: configDir() });
-        vaultSlotNames = v.list().map((s) => s.name);
+        const raw = await fs.readFile(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !parsed.config
+            || !parsed.config.stt || !parsed.config.tts) {
+            throw new Error('voice-config.json has no { version, config: { stt, tts } } shape');
+        }
+        if (parsed.version !== 1) {
+            throw new Error('voice-config.json version mismatch (got ' + String(parsed.version) + ', expected 1)');
+        }
+        cfg = parsed.config;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            /* Verified absent. VoiceRouter.loadConfig seeds the defaults on
+             * first use -- we report those WITHOUT writing them. */
+            cfg = DEFAULT_VOICE_CONFIG;
+            seeded = true;
+        }
+        else {
+            checks.push(mk({
+                id, name, status: 'unknown',
+                source: file,
+                expected: 'a voice-config.json with { version: 1, config: { stt, tts } }',
+                found: 'present but unreadable',
+                detail: couldNotVerify('the voice configuration', firstLine(err)),
+                hint: 'delete ' + file + ' to let the router re-seed the defaults, then `yf voice setup`',
+            }));
+            return;
+        }
+    }
+    const stt = resolveVoice('stt', cfg.stt.provider, keys);
+    const tts = resolveVoice('tts', cfg.tts.provider, keys);
+    const parts = [];
+    for (const [kind, r] of [['STT', stt], ['TTS', tts]]) {
+        if (r.resolved === null) {
+            parts.push(kind + ': ' + r.configured + ' configured, no credential, nothing else ready');
+        }
+        else if (r.configuredReady) {
+            parts.push(kind + ': ' + r.configured);
+        }
+        else {
+            parts.push(kind + ': ' + r.configured + ' configured but has no credential -- '
+                + 'runtime fallback resolves to ' + r.resolved);
+        }
     }
-    catch { /* vault not yet initialised */ }
-    let providerKeys = {};
+    /* A second file carries stt_provider / tts_provider fields that NO
+     * runtime path reads. Name it so the user is not sent to edit it. */
+    let conflict;
+    const legacy = path.join(dir, 'voice.json');
     try {
-        /* alpha.44 C1: keys live in the encrypted Vault. We still need
-         * the plaintext snapshot here to check "is brain configured?"
-         * style questions. The helper handles the legacy migration. */
-        const { readAllPlaintext } = await import('../core/provider_keys.js');
-        const all = await readAllPlaintext();
-        /* Preferences live alongside the keys in legacy JSON; if the
-         * legacy file still exists we read them, otherwise leave them
-         * undefined and let doctor render "none". */
-        const { promises: fsp } = await import('node:fs');
-        const os = await import('node:os');
-        const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-        /* Preferences (brain_provider_preference, model + stt/tts prefs) live in
-         * the CURRENT provider_keys.json: post-PND-051 that file holds the
-         * NON-secret metadata (the secret VALUES moved to the encrypted vault,
-         * read via readAllPlaintext above). Reading ONLY the .legacy.bak (which
-         * most installs do not have) dropped the preference, so the brain check
-         * reported "no brain provider configured" even with a provider + vault
-         * key set. Read both -- the current file wins. */
-        let prefsJson = {};
-        for (const f of ['provider_keys.json.legacy.bak', 'provider_keys.json']) {
-            try {
-                const raw = await fsp.readFile(path.join(home, '.yujin-forge', f), 'utf-8');
-                prefsJson = { ...prefsJson, ...JSON.parse(raw) };
-            }
-            catch { /* file absent -> skip */ }
+        const raw = await fs.readFile(legacy, 'utf-8');
+        const j = JSON.parse(raw);
+        const disagrees = (j.stt_provider && j.stt_provider !== cfg.stt.provider)
+            || (j.tts_provider && j.tts_provider !== cfg.tts.provider);
+        if (disagrees) {
+            conflict = legacy + ' says stt=' + String(j.stt_provider) + ' tts=' + String(j.tts_provider)
+                + ', but no runtime path reads those fields -- voice-config.json governs';
         }
-        providerKeys = {
-            ...prefsJson,
-            anthropic_api_key: all.anthropic_api_key ?? undefined,
-            openai_api_key: all.openai_api_key ?? undefined,
-            google_ai_key: all.google_ai_key ?? undefined,
-            google_stt_key: all.google_stt_key ?? undefined,
-            google_tts_key: all.google_tts_key ?? undefined,
-            whisper_api_key: all.whisper_api_key ?? undefined,
-            elevenlabs_api_key: all.elevenlabs_api_key ?? undefined,
-        };
-    }
-    catch { /* vault unavailable -- treat as empty */ }
-    const stt = [];
-    if (providerKeys.openai_api_key || vaultSlotNames.includes('openai'))
-        stt.push('OpenAI');
-    if (providerKeys.google_stt_key || vaultSlotNames.includes('google_voice'))
-        stt.push('Google');
-    const tts = [];
-    if (providerKeys.elevenlabs_api_key || vaultSlotNames.includes('elevenlabs'))
-        tts.push('ElevenLabs');
-    if (providerKeys.openai_api_key)
-        tts.push('OpenAI');
-    if (providerKeys.google_tts_key || vaultSlotNames.includes('google_voice'))
-        tts.push('Google');
-    checks.push({
-        name: 'Voice providers available (BYOK)',
-        ok: stt.length > 0 && tts.length > 0,
-        detail: 'STT: ' + (stt.length > 0 ? stt.join(' + ') : 'none')
-            + ' / TTS: ' + (tts.length > 0 ? tts.join(' + ') : 'none')
-            + (providerKeys.stt_provider_preference
-                ? ' / pref STT: ' + providerKeys.stt_provider_preference : '')
-            + (providerKeys.tts_provider_preference
-                ? ' / pref TTS: ' + providerKeys.tts_provider_preference : ''),
-        ...(stt.length === 0 || tts.length === 0 ? {
-            hint: 'run `yf keys setup` to configure brain + voice providers. Keys encrypt locally + sync to mobile automatically.',
-        } : {}),
-    });
-    /* 5. Brain provider (BYOK).
-     *
-     *  Forge is BYOK for the brain (Anthropic / OpenAI / Google AI /
-     *  DeepSeek) -- a single heavy dev burns $100-$200/mo, the
-     *  $10/mo platform fee cannot absorb that. The user picks
-     *  their provider via `yf keys setup` + pastes the key. The
-     *  encrypted key syncs to mobile automatically.
-     *
-     *  Check: provider_keys.json has a preference + the matching
-     *  key + (optionally) a model alias. */
-    const brainPref = (providerKeys.brain_provider_preference ?? null);
-    const brainKey = brainPref === 'anthropic' ? providerKeys.anthropic_api_key
-        : brainPref === 'openai' ? providerKeys.openai_api_key
-            : brainPref === 'google' ? providerKeys.google_ai_key
-                : brainPref === 'deepseek' ? providerKeys.deepseek_api_key
-                    : undefined;
-    const brainModel = brainPref === 'anthropic' ? providerKeys.anthropic_model_preference
-        : brainPref === 'openai' ? providerKeys.openai_brain_model_preference
-            : brainPref === 'google' ? providerKeys.google_brain_model_preference
-                : brainPref === 'deepseek' ? providerKeys.deepseek_model_preference
-                    : undefined;
-    if (brainPref && brainKey) {
-        checks.push({
-            name: 'Brain provider (BYOK: chat + code)',
-            ok: true,
-            detail: 'provider: ' + brainPref
-                + (brainModel ? ' / model: ' + brainModel : ' / model: (default for tier)'),
-        });
     }
-    else {
-        checks.push({
-            name: 'Brain provider (BYOK: chat + code)',
-            ok: false,
-            detail: brainPref
-                ? 'preference is ' + brainPref + ' but no API key on file for it'
-                : 'no brain provider configured -- chat + code will fail',
-            hint: 'run `yf keys setup` to pick a provider (Anthropic / OpenAI / Google AI / DeepSeek) and paste your API key',
-        });
-    }
-    /* 6. GitHub token. Optional -- only needed when chat tools
-     *  want to create repos / push commits. Marked OK by default
-     *  with an info detail when missing, so a clean install
-     *  doesn't show a red ✗ for a feature the user may not need. */
-    const hasGithub = vaultSlotNames.includes('github_token');
-    checks.push({
-        name: 'GitHub token (write-class tools)',
-        ok: true,
-        detail: hasGithub
+    catch { /* absent or unreadable: not this check's subject */ }
+    const working = stt.resolved !== null && tts.resolved !== null;
+    const drifted = working && (!stt.configuredReady || !tts.configuredReady);
+    checks.push(mk({
+        id, name,
+        status: working ? 'ok' : 'fail',
+        source: file + (seeded ? ' (absent -- router defaults reported)' : ''),
+        expected: 'the configured STT and TTS providers to have a credential',
+        found: 'stt=' + cfg.stt.provider + (stt.configuredReady ? ' ready' : ' no credential')
+            + ', tts=' + cfg.tts.provider + (tts.configuredReady ? ' ready' : ' no credential'),
+        detail: parts.join(' / '),
+        ...(conflict ? { conflict } : {}),
+        ...(working
+            ? (drifted ? { hint: 'voice works, but the configured provider is not the one that will run; '
+                    + 'run `yf voice setup` to make the config match, or add the missing key' } : {})
+            : { hint: 'run `yf keys setup` to configure voice providers (slot names only: '
+                    + 'google_stt_key / google_tts_key / elevenlabs / openai)' }),
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 5. Brain provider -- governing source is brain_config.json (F-01)   */
+/* ------------------------------------------------------------------ */
+async function checkBrainProvider(checks, dir, keys) {
+    const file = path.join(dir, 'brain_config.json');
+    const id = 'brain_provider';
+    const name = 'Brain provider (chat + code)';
+    if (!keys.vault_readable) {
+        checks.push(mk({
+            id, name, status: 'unknown',
+            source: file + ' + ' + path.join(dir, 'vault.json'),
+            expected: 'a provider per tier with a key for it',
+            found: 'the vault could not be opened, so key presence is unknowable',
+            detail: couldNotVerify('brain key presence', keys.vault_error ?? 'vault unreadable'),
+        }));
+        return;
+    }
+    let cfg;
+    let present = true;
+    try {
+        cfg = parseBrainConfig(await fs.readFile(file, 'utf-8'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            cfg = defaultBrainConfig();
+            present = false;
+        }
+        else {
+            checks.push(mk({
+                id, name, status: 'unknown',
+                source: file,
+                expected: 'a brain_config.json with an eco and a frontier tier',
+                found: 'present but unreadable',
+                detail: couldNotVerify('the brain routing', firstLine(err)),
+                hint: 'inspect ' + file + ' -- `yf brain reset` rewrites it with the defaults',
+            }));
+            return;
+        }
+    }
+    /* The flat brain_provider_preference in provider_keys.json is NOT
+     * what routes a chat turn: the cost router reads brain_config.json
+     * per tier. It is still live for the HITO 4 worker flows and the
+     * mobile brain client, so it is reported as a SEPARATE, derived
+     * source -- never as the subject of this check (F-01 / F-02). */
+    let conflict;
+    try {
+        const raw = await fs.readFile(path.join(dir, 'provider_keys.json'), 'utf-8');
+        const j = JSON.parse(raw);
+        const pref = j.brain_provider_preference;
+        if (pref && pref !== cfg[cfg.chat_default_tier].provider) {
+            conflict = path.join(dir, 'provider_keys.json') + ' has brain_provider_preference='
+                + pref + ', which serves the worker flows and the mobile brain, not this routing '
+                + '(see docs/BRAIN_SOURCES_OF_TRUTH.md)';
+        }
+    }
+    catch { /* absent or unreadable: not this check's subject */ }
+    const tiers = [
+        ['eco', cfg.eco],
+        ['frontier', cfg.frontier],
+        ['multimodal', cfg.multimodal],
+    ];
+    const parts = [];
+    const missing = [];
+    for (const [tier, binding] of tiers) {
+        if (!binding)
+            continue;
+        const slot = vaultSlotForProvider(binding.provider);
+        /* ollama is local and keyless; yujin_managed is served by the
+         * worker, whose auth is the yf_server_api_key check above. */
+        const keyless = binding.provider === 'ollama' || binding.provider === 'yujin_managed';
+        const hasIt = keyless || keys.status[slot] === true
+            || keys.vault_slots.includes(slot);
+        parts.push(tier + ': ' + binding.provider + '/' + binding.model
+            + (keyless ? ' (keyless)' : hasIt ? ' (key set)' : ' (NO KEY in slot ' + slot + ')'));
+        if (!hasIt)
+            missing.push(tier + ' -> slot ' + slot);
+    }
+    const serving = cfg.eco_enabled ? ['eco', 'frontier'] : ['frontier'];
+    const blocking = serving.filter((t) => missing.some((m) => m.startsWith(t + ' ')));
+    checks.push(mk({
+        id, name,
+        status: blocking.length === 0 ? 'ok' : 'fail',
+        source: file + (present ? '' : ' (absent -- runtime defaults reported)')
+            + ' + ' + path.join(dir, 'vault.json'),
+        expected: 'every serving tier to name a provider with a key in its slot',
+        found: present
+            ? parts.join('; ')
+            : 'brain_config.json absent, so the runtime uses the built-in defaults: ' + parts.join('; '),
+        detail: parts.join(' / ') + ' / default tier: ' + cfg.chat_default_tier,
+        ...(conflict ? { conflict } : {}),
+        ...(blocking.length === 0 ? {} : {
+            hint: 'the tier that cannot run is ' + blocking.join(' + ') + ' (' + missing.join(', ')
+                + '). Set the key for THAT slot with `yf keys setup`, or point the tier at a provider '
+                + 'you already have a key for with `yf brain set`',
+        }),
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 6. GitHub token                                                     */
+/* ------------------------------------------------------------------ */
+async function checkGithubToken(checks, keys) {
+    const src = path.join(keys.config_dir, 'vault.json') + ' (slot github_token)';
+    if (!keys.vault_readable) {
+        checks.push(mk({
+            id: 'github_token',
+            name: 'GitHub token (write-class tools, optional)',
+            status: 'unknown',
+            source: src,
+            expected: 'the slot github_token present or absent',
+            found: 'the vault could not be opened',
+            detail: couldNotVerify('whether the github_token slot is set', keys.vault_error ?? 'vault unreadable'),
+        }));
+        return;
+    }
+    const has = keys.vault_slots.includes('github_token');
+    checks.push(mk({
+        id: 'github_token',
+        name: 'GitHub token (write-class tools, optional)',
+        status: 'ok',
+        source: src,
+        expected: 'the slot github_token present or absent',
+        found: has ? 'present' : 'absent',
+        detail: has
             ? 'github_token slot configured'
-            : '(optional; not configured -- only needed for forge.create_github_repo / forge.git_push)',
-    });
-    /* 5. i18n catalogs + manuals (Fase F). All 10 locales must
-       load + the 10 manual HTML files must exist on disk. */
+            : '(optional; absent -- only needed for forge.create_github_repo / forge.git_push)',
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 7. i18n catalogs                                                    */
+/* ------------------------------------------------------------------ */
+async function checkI18nCatalogs(checks) {
+    const id = 'i18n_catalogs';
+    const name = 'i18n catalogs (10 languages)';
     try {
         const { lintCatalogs, SUPPORTED_LANGUAGES } = await import('../i18n/index.js');
         const lintResult = lintCatalogs();
-        checks.push({
-            name: 'i18n catalogs (10 languages)',
-            ok: lintResult.missing.length === 0,
-            detail: lintResult.missing.length === 0
+        const clean = lintResult.missing.length === 0;
+        checks.push(mk({
+            id, name,
+            status: clean ? 'ok' : 'fail',
+            source: 'src/i18n/catalogs/*.json, loaded through src/i18n/index.js (the same loader the panel uses)',
+            expected: SUPPORTED_LANGUAGES.length + ' catalogs with no missing key',
+            found: clean ? 'complete' : lintResult.missing.length + ' missing key(s)',
+            detail: clean
                 ? SUPPORTED_LANGUAGES.length + ' catalogs complete'
                 : lintResult.missing.length + ' missing key(s) -- first: '
                     + lintResult.missing[0].lang + ':' + lintResult.missing[0].key,
-            ...(lintResult.missing.length > 0 ? { hint: 'run scripts/catalog_lint to see all gaps' } : {}),
-        });
+            ...(clean ? {} : { hint: 'run `npm run catalog:lint` to see all gaps' }),
+        }));
     }
     catch (err) {
-        checks.push({
-            name: 'i18n catalogs (10 languages)',
-            ok: false,
-            detail: 'load failed: ' + (err instanceof Error ? err.message : String(err)),
+        checks.push(mk({
+            id, name,
+            status: 'unknown',
+            source: 'src/i18n/index.js',
+            expected: 'the i18n module to load',
+            found: 'import threw',
+            detail: couldNotVerify('the catalogs', firstLine(err)),
             hint: 'check src/i18n/catalogs/*.json',
-        });
+        }));
     }
-    /* 5b. Hardcoded user-facing strings -- panel + server source
-       scanned for literals that should flow through the i18n
-       catalog. Anti-debt: this catches the same class of bug
-       the 600-suite followup audit found before we accumulate
-       more. */
+}
+/* ------------------------------------------------------------------ */
+/* 8. Hardcoded strings lint -- must never DISAPPEAR (PND-187)         */
+/* ------------------------------------------------------------------ */
+async function checkHardcodedStrings(checks) {
+    const id = 'hardcoded_strings';
+    const name = 'Hardcoded user-facing strings (i18n compliance)';
+    let script = '(unresolved)';
     try {
-        const { execSync } = await import('node:child_process');
         const { fileURLToPath } = await import('node:url');
-        const pathMod = await import('node:path');
-        const here = pathMod.dirname(fileURLToPath(import.meta.url));
-        /* From dist/commands/ go up two levels to repo root, then
-           into scripts/. The same path works under tsx because
-           src/commands/ is also two levels deep. */
-        const script = pathMod.resolve(here, '..', '..', 'scripts', 'lint_hardcoded_strings.mjs');
-        let scriptExists = false;
-        try {
-            const fsMod = await import('node:fs/promises');
-            await fsMod.stat(script);
-            scriptExists = true;
-        }
-        catch { /* script not packaged in the published tarball */ }
-        if (scriptExists) {
-            try {
-                const out = execSync('node ' + JSON.stringify(script), {
-                    stdio: ['ignore', 'pipe', 'pipe'],
-                }).toString();
-                const clean = /lint_hardcoded_strings: clean\./.test(out);
-                checks.push({
-                    name: 'Hardcoded user-facing strings (i18n compliance)',
-                    ok: clean,
-                    detail: clean ? 'panel + server source clean' : 'findings present',
-                    ...(clean ? {} : { hint: 'run scripts/lint_hardcoded_strings.mjs to see them' }),
-                });
-            }
-            catch (err) {
-                const detail = err instanceof Error ? err.message.slice(0, 80) : String(err).slice(0, 80);
-                checks.push({
-                    name: 'Hardcoded user-facing strings (i18n compliance)',
-                    ok: false,
-                    detail: 'lint failed: ' + detail,
-                    hint: 'run scripts/lint_hardcoded_strings.mjs --strict',
-                });
-            }
-        }
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        /* From dist/commands/ (and src/commands/ under tsx) go up two
+         * levels to the package root, then into scripts/. */
+        script = path.resolve(here, '..', '..', 'scripts', 'lint_hardcoded_strings.mjs');
+        await fs.stat(script);
     }
     catch {
-        /* node:child_process not available in this runtime; skip. */
+        /* scripts/ is not in package.json "files", so EVERY npm install
+         * lands here. Previously the check was simply not pushed and the
+         * user had no way to know a check had gone missing. */
+        checks.push(mk({
+            id, name,
+            status: 'unknown',
+            source: script,
+            expected: 'the lint script on disk',
+            found: 'absent -- scripts/ is not shipped in the published package',
+            detail: couldNotVerify('i18n string compliance', 'the lint script is not part of this install'),
+            hint: 'this lint runs in CI and from a source checkout; it is not available from an npm install',
+        }));
+        return;
     }
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const out = execFileSync(process.execPath, [script], { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+        const clean = /lint_hardcoded_strings: clean\./.test(out);
+        checks.push(mk({
+            id, name,
+            status: clean ? 'ok' : 'fail',
+            source: script,
+            expected: 'the marker line "lint_hardcoded_strings: clean."',
+            found: clean ? 'clean' : 'findings present',
+            detail: clean ? 'panel + server source clean' : 'findings present',
+            ...(clean ? {} : { hint: 'run `node scripts/lint_hardcoded_strings.mjs` to see them' }),
+        }));
+    }
+    catch (err) {
+        /* The script RAN and exited non-zero, OR the spawn failed. Those
+         * are different outcomes: a non-zero exit with output is a real
+         * finding, a spawn failure is a tool error we did not verify. */
+        const e = err;
+        const ranAndFailed = typeof e.status === 'number';
+        checks.push(mk({
+            id, name,
+            status: ranAndFailed ? 'fail' : 'unknown',
+            source: script,
+            expected: 'the marker line "lint_hardcoded_strings: clean."',
+            found: ranAndFailed ? 'exit code ' + e.status : 'the script could not be run',
+            detail: ranAndFailed
+                ? 'lint reported findings (exit ' + e.status + ')'
+                : couldNotVerify('i18n string compliance', firstLine(err)),
+            ...(ranAndFailed ? { hint: 'run `node scripts/lint_hardcoded_strings.mjs` to see them' } : {}),
+        }));
+    }
+}
+/* ------------------------------------------------------------------ */
+/* 9. Manuals                                                          */
+/* ------------------------------------------------------------------ */
+async function checkUserManuals(checks) {
+    const id = 'user_manuals';
+    const name = 'User manuals (HTML, 10 languages)';
     try {
         const { listAvailableManuals } = await import('../chat/tools/manual.js');
         const present = await listAvailableManuals();
-        checks.push({
-            name: 'User manuals (HTML, 10 languages)',
-            ok: present.length === 10,
-            detail: present.length + '/10 manuals available: ' + present.join(', '),
+        checks.push(mk({
+            id, name,
+            status: present.length === 10 ? 'ok' : 'fail',
+            source: 'docs/manuals/, enumerated through chat/tools/manual.js (the same lookup `yf manual` uses)',
+            expected: '10 manuals',
+            found: present.length + ': ' + (present.join(', ') || '(none)'),
+            detail: present.length + '/10 manuals available: ' + (present.join(', ') || '(none)'),
             ...(present.length < 10 ? { hint: 'reinstall the package or check docs/manuals/' } : {}),
-        });
+        }));
     }
     catch (err) {
-        checks.push({
-            name: 'User manuals (HTML, 10 languages)',
-            ok: false,
-            detail: 'probe failed: ' + (err instanceof Error ? err.message : String(err)),
-        });
-    }
-    /* 6. Reader parser dependencies (HITO 1). PDF + DOCX + XLSX
-       use lazy-loaded npm deps; verify they resolve. */
-    for (const [label, modPath] of [
-        ['pdfjs-dist (PDF reader)', 'pdfjs-dist/legacy/build/pdf.mjs'],
-        ['mammoth (DOCX reader)', 'mammoth'],
-        ['xlsx (XLSX reader)', 'xlsx'],
-    ]) {
+        checks.push(mk({
+            id, name,
+            status: 'unknown',
+            source: 'src/chat/tools/manual.js',
+            expected: 'the manual lookup to run',
+            found: 'probe threw',
+            detail: couldNotVerify('the manuals', firstLine(err)),
+        }));
+    }
+}
+/* ------------------------------------------------------------------ */
+/* 10. Reader deps                                                     */
+/* ------------------------------------------------------------------ */
+async function checkReaderDeps(checks) {
+    const deps = [
+        ['reader_pdfjs', 'pdfjs-dist (PDF reader)', 'pdfjs-dist/legacy/build/pdf.mjs'],
+        ['reader_mammoth', 'mammoth (DOCX reader)', 'mammoth'],
+        ['reader_xlsx', 'xlsx (XLSX reader)', 'xlsx'],
+    ];
+    for (const [id, name, modPath] of deps) {
         try {
+            /* The real readiness test: run the same lazy import the reader
+             * runs. Nothing short of that proves the dep resolves here. */
             /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
             await import(modPath);
-            checks.push({
-                name: label,
-                ok: true,
+            checks.push(mk({
+                id, name,
+                status: 'ok',
+                source: "import('" + modPath + "') -- the same specifier the reader uses",
+                expected: 'the module to resolve',
+                found: 'resolved',
                 detail: 'lazy-import resolved',
-            });
+            }));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            checks.push({
-                name: label,
-                ok: false,
-                detail: 'import failed: ' + msg.split('\n')[0],
+            checks.push(mk({
+                id, name,
+                status: 'fail',
+                source: "import('" + modPath + "') -- the same specifier the reader uses",
+                expected: 'the module to resolve',
+                found: 'import failed',
+                detail: 'import failed: ' + firstLine(err),
                 hint: 'run `npm install` from the Forge install directory',
-            });
+            }));
         }
     }
-    /* 6. Recap summary opt-in env var (informational). */
+}
+/* ------------------------------------------------------------------ */
+/* 11. Recap mode                                                      */
+/* ------------------------------------------------------------------ */
+function checkRecapMode(checks) {
     const recapEnabled = process.env['YF_ENABLE_CLAUDE_RECAP'] === '1';
-    checks.push({
-        name: 'Claude recap summary mode',
-        ok: true,
+    checks.push(mk({
+        id: 'recap_mode',
+        name: 'Claude recap summary mode (informational)',
+        status: 'ok',
+        source: 'env YF_ENABLE_CLAUDE_RECAP -- the same var src/reader/index.ts reads',
+        expected: "'1' to enable",
+        found: recapEnabled ? "'1'" : 'unset or not 1',
         detail: recapEnabled
-            ? 'enabled (YF_ENABLE_CLAUDE_RECAP=1; charges tokens per recap)'
+            ? 'enabled (charges tokens per recap)'
             : 'disabled (literal mode only; set YF_ENABLE_CLAUDE_RECAP=1 to enable; see docs/RECAP_CLAUDE_COSTS.md)',
-    });
-    /* 7. Project root sanity. */
+    }));
+}
+/* ------------------------------------------------------------------ */
+/* 12. Project root                                                    */
+/* ------------------------------------------------------------------ */
+async function checkProjectRoot(checks, cwd) {
+    let readable = false;
     try {
-        const cwd = process.cwd();
         const stat = await fs.stat(cwd);
-        checks.push({
+        readable = stat.isDirectory();
+        checks.push(mk({
+            id: 'cwd_readable',
             name: 'Current working directory readable',
-            ok: stat.isDirectory(),
+            status: readable ? 'ok' : 'fail',
+            source: cwd,
+            expected: 'a readable directory',
+            found: readable ? 'directory' : 'not a directory',
             detail: cwd,
-        });
-        /* Look for typical Forge project markers; absence is
-           informational, not a failure -- yf doctor runs anywhere. */
-        const hasManifest = await fs.access(path.join(cwd, 'manifest.json')).then(() => true, () => false);
-        const hasPackage = await fs.access(path.join(cwd, 'package.json')).then(() => true, () => false);
-        checks.push({
-            name: 'Project markers',
-            ok: true,
-            detail: (hasPackage ? 'package.json' : '') + (hasManifest ? (hasPackage ? ' + ' : '') + 'manifest.json' : '')
-                || '(neither package.json nor manifest.json in cwd)',
-        });
+        }));
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        checks.push({
+        checks.push(mk({
+            id: 'cwd_readable',
             name: 'Current working directory readable',
-            ok: false,
-            detail: msg,
-        });
+            status: 'fail',
+            source: cwd,
+            expected: 'a readable directory',
+            found: 'stat failed',
+            detail: firstLine(err),
+        }));
     }
-    return checks;
+    if (!readable) {
+        checks.push(mk({
+            id: 'project_markers',
+            name: 'Project markers in the working directory',
+            status: 'unknown',
+            source: cwd,
+            expected: 'package.json and/or manifest.json',
+            found: 'the directory could not be read',
+            detail: couldNotVerify('the project markers', 'the working directory is not readable'),
+        }));
+        return;
+    }
+    const hasManifest = await fs.access(path.join(cwd, 'manifest.json')).then(() => true, () => false);
+    const hasPackage = await fs.access(path.join(cwd, 'package.json')).then(() => true, () => false);
+    const found = [hasPackage ? 'package.json' : null, hasManifest ? 'manifest.json' : null]
+        .filter(Boolean).join(' + ');
+    checks.push(mk({
+        id: 'project_markers',
+        name: 'Project markers in the working directory',
+        status: 'ok',
+        source: cwd,
+        expected: 'package.json and/or manifest.json (absence is informational -- doctor runs anywhere)',
+        found: found || 'neither',
+        detail: found || '(neither package.json nor manifest.json in cwd)',
+    }));
 }
+/* ------------------------------------------------------------------ */
+/* HITO 4 probes                                                       */
+/* ------------------------------------------------------------------ */
 /** PND-031 -- 3 HITO 4 doctor probes. Extracted so tests can
  *  exercise them with injected fetch + tmp config dir without
  *  spinning the whole doctor runner. */
@@ -390,86 +720,121 @@ export async function runHito4DoctorChecks(checks, opts = {}) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 4_000;
     const now = (opts.nowMs ?? (() => Date.now()))();
+    const dir = opts.configDir ?? configDir();
     /* (a) HITO 4 worker reachable. The worker's health route is /healthz
      * (Hono app.get('/healthz')); hitting /v1/health returned a misleading
      * 404 "unhealthy" even when the worker was fully up. */
+    const healthUrl = baseUrl.replace(/\/+$/, '') + '/healthz';
     try {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), timeoutMs);
         try {
-            const r = await fetchImpl(baseUrl.replace(/\/+$/, '') + '/healthz', {
-                method: 'GET',
-                signal: ctrl.signal,
-            });
-            checks.push({
+            const r = await fetchImpl(healthUrl, { method: 'GET', signal: ctrl.signal });
+            checks.push(mk({
+                id: 'hito4_worker',
                 name: 'HITO 4 worker reachable (' + baseUrl + ')',
-                ok: r.ok,
+                status: r.ok ? 'ok' : 'fail',
+                source: 'GET ' + healthUrl,
+                expected: 'HTTP 2xx',
+                found: 'HTTP ' + r.status,
                 detail: r.ok ? 'HTTP ' + r.status : 'HTTP ' + r.status + ' (worker responded but unhealthy)',
                 ...(r.ok ? {} : { hint: 'check worker status / Cloudflare dashboard' }),
-            });
+            }));
         }
         finally {
             clearTimeout(timer);
         }
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        checks.push({
+        /* No answer at all. We did not verify the worker is DOWN -- we
+         * verified we could not reach it from here, which a firewall, a
+         * proxy or an offline laptop also produce. */
+        checks.push(mk({
+            id: 'hito4_worker',
             name: 'HITO 4 worker reachable (' + baseUrl + ')',
-            ok: false,
-            detail: 'unreachable: ' + msg.slice(0, 80),
+            status: 'unknown',
+            source: 'GET ' + healthUrl,
+            expected: 'HTTP 2xx',
+            found: 'no response (' + firstLine(err) + ')',
+            detail: couldNotVerify('the worker', 'unreachable from this machine: ' + firstLine(err)),
             hint: 'check internet, DNS, or set YF_HITO4_BASE_URL for a staging override',
-        });
+        }));
     }
     /* (b) worker-auth signing key configured. The HITO 4 client signs every
      * call with the per-handle key (`yf_handle_key`, derived on first use)
-     * or the root key (`yf_server_api_key`, "the value provided at signup").
-     * `yujin_license` was a legacy slot name that nothing reads anymore --
-     * checking it flagged a phantom "missing" on every install. Only needed
-     * for worker-backed features (mobile relay, managed brain, voice
-     * gateway, license sync); BYOK desktop chat works without it. */
-    try {
-        const v = await Vault.open({ configDir: configDir() });
-        const has = v.has('yf_handle_key') || v.has('yf_server_api_key');
-        checks.push({
-            name: 'Vault slot yf_server_api_key (worker auth)',
-            ok: has,
+     * or the root key (`yf_server_api_key`). Only needed for worker-backed
+     * features (mobile relay, managed brain, voice gateway, license sync);
+     * BYOK desktop chat works without it. */
+    const vaultFile = path.join(dir, 'vault.json');
+    let vaultSlots = null;
+    let vaultErr = null;
+    const vaultPresent = await fs.stat(vaultFile).then(() => true, () => false);
+    if (vaultPresent) {
+        try {
+            const v = await Vault.open({ configDir: dir });
+            vaultSlots = v.list().map((s) => s.name);
+        }
+        catch (err) {
+            vaultErr = firstLine(err);
+        }
+    }
+    else {
+        vaultSlots = [];
+    }
+    if (vaultSlots === null) {
+        checks.push(mk({
+            id: 'worker_auth_key',
+            name: 'Worker auth key (mobile relay / managed brain / license sync)',
+            status: 'unknown',
+            source: vaultFile + ' (slots yf_handle_key, yf_server_api_key)',
+            expected: 'one of the two slots present',
+            found: 'the vault could not be opened',
+            detail: couldNotVerify('the worker auth slots', vaultErr ?? 'vault unreadable'),
+        }));
+    }
+    else {
+        const has = vaultSlots.includes('yf_handle_key') || vaultSlots.includes('yf_server_api_key');
+        checks.push(mk({
+            id: 'worker_auth_key',
+            name: 'Worker auth key (mobile relay / managed brain / license sync)',
+            status: has ? 'ok' : 'fail',
+            source: vaultFile + ' (slots yf_handle_key, yf_server_api_key)',
+            expected: 'one of the two slots present',
+            found: has ? 'present' : 'neither slot present',
             detail: has ? 'configured' : 'missing (only needed for mobile relay / managed brain / voice / license sync)',
             ...(has ? {} : { hint: 'run `yf vault set yf_server_api_key` with the value provided at signup' }),
-        });
-    }
-    catch (err) {
-        /* Vault not initialised is the expected pre-install state. */
-        checks.push({
-            name: 'Vault slot yf_server_api_key (worker auth)',
-            ok: false,
-            detail: 'vault not initialised',
-            hint: 'open the chat panel once (or run `yf vault set yf_server_api_key`) to create the vault',
-        });
+        }));
     }
     /* (c) license.json cached < 24h. */
+    const licPath = path.join(dir, 'license.json');
     try {
-        const licPath = path.join(configDir(), 'license.json');
         const stat = await fs.stat(licPath);
         const ageMs = now - stat.mtimeMs;
         const ageHours = Math.round(ageMs / 3_600_000);
         const fresh = ageMs < 24 * 3_600_000;
-        checks.push({
+        checks.push(mk({
+            id: 'license_cache',
             name: 'License cache freshness (license.json)',
-            ok: fresh,
-            detail: fresh
-                ? 'updated ' + ageHours + 'h ago'
-                : 'stale: last updated ' + ageHours + 'h ago (> 24h)',
+            status: fresh ? 'ok' : 'fail',
+            source: licPath + ' (mtime)',
+            expected: 'mtime within 24h',
+            found: ageHours + 'h old',
+            detail: fresh ? 'updated ' + ageHours + 'h ago' : 'stale: last updated ' + ageHours + 'h ago (> 24h)',
             ...(fresh ? {} : { hint: 'run `yf license sync` to refresh from the server' }),
-        });
+        }));
     }
-    catch {
-        checks.push({
+    catch (err) {
+        const absent = err.code === 'ENOENT';
+        checks.push(mk({
+            id: 'license_cache',
             name: 'License cache freshness (license.json)',
-            ok: false,
-            detail: 'no license.json yet',
+            status: absent ? 'fail' : 'unknown',
+            source: licPath + ' (mtime)',
+            expected: 'mtime within 24h',
+            found: absent ? 'file absent' : 'stat failed',
+            detail: absent ? 'no license.json yet' : couldNotVerify('the license cache age', firstLine(err)),
             hint: 'run `yf license activate --user-handle <you@example.com>` then `yf license sync`',
-        });
+        }));
     }
 }
 //# sourceMappingURL=doctor.js.map