@thinkrun/cli 0.1.27

package/dist/src/commands/doctor.js

@@ -0,0 +1,684 @@
+/**
+ * Diagnostic command for local/cloud endpoint clarity.
+ * Reflects effective command-path health: warns when routing would fail.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { config } from '../config/store.js';
+import { resolveRegistrationExtensionIdFromSources } from './install.js';
+import { isLocalApiUrl, readBridgePort as _readBridgePort, DEFAULT_BRIDGE_PORT as _DEFAULT_BRIDGE_PORT, getBridgePortFileMtimeMs, getStaleBridgePortFileAgeMs, } from '../utils.js';
+import { getResolutionInfo } from '../adapters/index.js';
+import { checkNativeHost, isValidExtensionId, resolveExtensionId, } from './install.js';
+import { getSessionContext } from '../session/context.js';
+import { getDaemonJsonPath } from '../daemon/access.js';
+import { probeDaemonHealth, DAEMON_PROTOCOL_VERSION, isPidAlive } from '../daemon/utils.js';
+import { existsSync, readFileSync } from 'fs';
+import { execSync } from 'child_process';
+/** Prefix used by the native-host circuit breaker when setting lastDisconnectReason. */
+export const CIRCUIT_BREAKER_REASON_PREFIX = 'Circuit breaker:';
+export function getManifestRegistrationIssue(opts) {
+    if (Array.isArray(opts.manifestEntries)) {
+        const relevantEntries = opts.manifestEntries.filter((entry) => entry.relevant);
+        if (relevantEntries.length > 0) {
+            const hasMatchingRelevantEntry = relevantEntries.some((entry) => entry.manifestParseStatus === 'parsed' &&
+                Array.isArray(entry.manifestExtensionIds) &&
+                entry.manifestExtensionIds.includes(opts.effectiveExtensionId));
+            const hasDisagreeingRelevantEntry = relevantEntries.some((entry) => !entry.manifestExists ||
+                entry.manifestParseStatus !== 'parsed' ||
+                !Array.isArray(entry.manifestExtensionIds) ||
+                !entry.manifestExtensionIds.includes(opts.effectiveExtensionId));
+            if (hasMatchingRelevantEntry && hasDisagreeingRelevantEntry) {
+                return 'inconsistent';
+            }
+            if (hasMatchingRelevantEntry) {
+                return null;
+            }
+            if (relevantEntries.some((entry) => entry.manifestParseStatus === 'parse_error')) {
+                return 'parse_error';
+            }
+            if (relevantEntries.some((entry) => !entry.manifestExists)) {
+                return 'missing';
+            }
+            return 'wrong_id';
+        }
+    }
+    if (Array.isArray(opts.manifestExtensionIds)) {
+        return opts.manifestExtensionIds.includes(opts.effectiveExtensionId) ? null : 'wrong_id';
+    }
+    if (isValidExtensionId(opts.registeredExtensionId)
+        && opts.registeredExtensionId !== opts.effectiveExtensionId) {
+        return 'wrong_id';
+    }
+    return null;
+}
+export function hasExtensionRegistrationMismatch(opts) {
+    return getManifestRegistrationIssue(opts) !== null;
+}
+export function resolveDoctorExtensionId(opts) {
+    return resolveRegistrationExtensionIdFromSources({
+        extensionId: opts.resolvedExtensionId.source === 'flag' ? opts.resolvedExtensionId.extensionId : undefined,
+        envExtensionId: opts.resolvedExtensionId.source === 'env' ? opts.resolvedExtensionId.extensionId : undefined,
+        configuredExtensionId: opts.resolvedExtensionId.source === 'config' ? opts.resolvedExtensionId.extensionId : undefined,
+        registeredExtensionId: opts.registeredExtensionId,
+        preferPackagedDefaultExtensionId: opts.preferPackagedDefaultExtensionId,
+        manifestExtensionIds: opts.manifestExtensionIds,
+        manifestParseStatus: opts.manifestParseStatus,
+        manifestExists: opts.manifestExists,
+    });
+}
+// Re-exported for backward compatibility — consumers should import from '../utils.js' directly.
+export const DEFAULT_BRIDGE_PORT = _DEFAULT_BRIDGE_PORT;
+export const readBridgePort = _readBridgePort;
+export async function checkHealth(url, apiKey, fetchFn = fetch) {
+    try {
+        let healthUrl;
+        try {
+            const base = new URL(url);
+            if (base.protocol !== 'http:' && base.protocol !== 'https:') {
+                return { ok: false, message: `Unsupported protocol: ${base.protocol}` };
+            }
+            const baseHref = base.href.endsWith('/') ? base.href : `${base.href}/`;
+            healthUrl = new URL('health', baseHref).toString();
+        }
+        catch {
+            return { ok: false, message: 'Invalid URL' };
+        }
+        const headers = {};
+        if (apiKey)
+            headers['x-api-key'] = apiKey;
+        const res = await fetchFn(healthUrl, {
+            headers,
+            signal: AbortSignal.timeout(2500),
+        });
+        if (!res.ok) {
+            return { ok: false, message: `HTTP ${res.status}` };
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            return { ok: false, message: 'Invalid /health response (not JSON)' };
+        }
+        const inner = body?.data;
+        const svc = inner?.service || body?.service;
+        const extConnected = typeof inner?.extensionConnected === 'boolean'
+            ? inner.extensionConnected
+            : typeof body?.extensionConnected === 'boolean'
+                ? body.extensionConnected
+                : undefined;
+        const browserName = inner?.browser?.name ?? body?.browser?.name;
+        const lastReason = inner?.lastExtensionDisconnectReason ?? body?.lastExtensionDisconnectReason;
+        const lastAt = inner?.lastExtensionDisconnectAt ?? body?.lastExtensionDisconnectAt;
+        // The local native-host /health producer already emits these recovery fields
+        // (see extension/native-host/routes.ts -> handleHealth). Keep reading both the
+        // nested `data` shape and the flat shape because older callers may proxy either.
+        const recoveryState = inner?.recoveryState ?? body?.recoveryState;
+        const recentDisconnectCount = typeof inner?.recentDisconnectCount === 'number'
+            ? inner.recentDisconnectCount
+            : typeof body?.recentDisconnectCount === 'number'
+                ? body.recentDisconnectCount
+                : undefined;
+        const lastRecoveredAt = inner?.lastRecoveredAt ?? body?.lastRecoveredAt;
+        if (svc) {
+            if (typeof extConnected === 'boolean') {
+                const browserSuffix = typeof browserName === 'string' ? `, browser=${browserName}` : '';
+                let msg = `${svc} (extensionConnected=${extConnected}${browserSuffix})`;
+                if (typeof recoveryState === 'string' && recoveryState !== 'healthy') {
+                    msg += `, recoveryState=${recoveryState}`;
+                }
+                if (typeof recentDisconnectCount === 'number' && recentDisconnectCount > 0) {
+                    msg += `, recentDisconnects=${recentDisconnectCount}`;
+                }
+                if (typeof lastRecoveredAt === 'string' && lastRecoveredAt.length > 0) {
+                    msg += `, lastRecoveredAt=${lastRecoveredAt}`;
+                }
+                const shouldSurfaceLastDisconnect = typeof lastReason === 'string' &&
+                    lastReason.length > 0 &&
+                    (extConnected === false || recoveryState === 'recently_recovered' || recoveryState === 'flapping');
+                if (shouldSurfaceLastDisconnect) {
+                    msg += `, lastDisconnect=${lastReason}`;
+                    if (typeof lastAt === 'string' && lastAt.length > 0)
+                        msg += ` @ ${lastAt}`;
+                }
+                const disconnectReason = typeof lastReason === 'string' ? lastReason : undefined;
+                // Only set isCircuitBreakerTrip when the extension is actually disconnected;
+                // leave undefined when connected so callers can distinguish "connected" from "disconnected but not CB".
+                // Note: the native host clears lastExtensionDisconnectReason on reconnect (bridge-server.ts line 493),
+                // so a stale CB reason will never appear when extensionConnected=true — no freshness guard needed.
+                const isCircuitBreakerTrip = extConnected === false && typeof disconnectReason === 'string'
+                    ? disconnectReason.startsWith(CIRCUIT_BREAKER_REASON_PREFIX)
+                    : undefined;
+                return {
+                    ok: true,
+                    message: msg,
+                    extensionConnected: extConnected,
+                    lastDisconnectReason: disconnectReason,
+                    recoveryState,
+                    recentDisconnectCount,
+                    lastRecoveredAt,
+                    isCircuitBreakerTrip,
+                };
+            }
+            return { ok: true, message: `${svc}` };
+        }
+        return { ok: true, message: 'healthy' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unreachable';
+        return { ok: false, message };
+    }
+}
+/**
+ * Classify the current disconnect state into one of four mutually exclusive buckets.
+ *
+ * Priority order (highest to lowest):
+ *   daemon_down > breaker_open > socket_down > socket_up_tab_gone
+ */
+export function classifyDisconnectState(opts) {
+    if (!opts.daemonReachable) {
+        return {
+            state: 'daemon_down',
+            hint: 'Daemon is not running. Run: thinkrun setup or thinkrun doctor --fix',
+        };
+    }
+    if (opts.isBreakerOpen) {
+        return {
+            state: 'breaker_open',
+            hint: 'Circuit breaker is open from repeated transport failures. Run: thinkrun reset-connection',
+        };
+    }
+    if (opts.extensionSocketConnected === false) {
+        return {
+            state: 'socket_down',
+            hint: 'Extension is not connected to the daemon. Reload the ThinkRun extension or restart the browser.',
+        };
+    }
+    if (opts.extensionSocketConnected === undefined) {
+        // Daemon is up but we haven't observed the socket state — do NOT conclude
+        // the tab is gone (that requires a confirmed-up socket).
+        return {
+            state: 'socket_state_unknown',
+            hint: 'Daemon is up but the extension socket state is unknown yet. Retry shortly, or run: thinkrun doctor',
+        };
+    }
+    return {
+        state: 'socket_up_tab_gone',
+        hint: 'The attached tab is no longer available. Run: thinkrun attach <tabId>',
+    };
+}
+// Returns plain-text hint for extension disconnect (circuit-breaker vs reload branch); exported for testing.
+export function getExtensionDisconnectHint(result, disconnectStateOpts) {
+    if (result.recoveryState === 'recovering') {
+        return 'Bridge is reconnecting automatically after a recent disconnect. Wait a few seconds, then retry the command.';
+    }
+    if (result.recoveryState === 'flapping') {
+        return 'Bridge is flapping from repeated disconnects. Avoid patient retry loops; reload the ThinkRun extension or stabilize the page/browser before retrying.';
+    }
+    if (result.recoveryState === 'recently_recovered') {
+        return 'Bridge recently recovered from disconnect churn. If the next local command still fails, retry once before assuming the bridge is fully healthy.';
+    }
+    if (result.extensionConnected !== false)
+        return null;
+    // When full signal data is available, use the structured taxonomy for a precise hint.
+    if (disconnectStateOpts) {
+        const diagnosis = classifyDisconnectState(disconnectStateOpts);
+        return diagnosis.hint;
+    }
+    if (result.isCircuitBreakerTrip) {
+        return 'False circuit-breaker trip. Run: thinkrun reset-connection';
+    }
+    // No reason available or non-CB disconnect — default to reload guidance (safer than reset-connection).
+    return 'Extension disconnected. Reload the ThinkRun extension in your Chromium-based browser.';
+}
+export function getSuggestedNextStep(opts) {
+    const { apiKey, localEndpoint, apiHealthOk, activeLocalTabId, activeCloudSessionId, activeSessionId, bridgeRelevant, bridgeHealthOk, commandPathOk, extensionConnected, isCircuitBreakerTrip, recoveryState, recentDisconnectCount, configuredExtensionId, extensionIdSource, manifestMismatch, manifestIssue, manifestParseStatus, } = opts;
+    if (bridgeRelevant && bridgeHealthOk === false) {
+        if (manifestIssue === 'inconsistent') {
+            return 'Local native-host manifests disagree across detected Chromium-based browsers. Run: thinkrun setup';
+        }
+        if (manifestIssue === 'parse_error' || manifestParseStatus === 'parse_error') {
+            return 'Local native-host manifest is unreadable. Run: thinkrun setup';
+        }
+        if (manifestIssue === 'missing') {
+            return 'Local native-host manifest is missing for a detected Chromium-based browser. Run: thinkrun setup';
+        }
+        if (manifestMismatch && extensionIdSource === 'default') {
+            return 'Local bridge is unreachable. If you are using the packaged ThinkRun extension, rerun: thinkrun setup\nIf you are using an unpacked/dev extension, copy its ID from chrome://extensions and run: thinkrun config set-extension-id <id>\nThen rerun: thinkrun setup';
+        }
+        if (manifestMismatch && configuredExtensionId) {
+            return `Local bridge is unreachable. Verify the installed ThinkRun extension ID in chrome://extensions matches ${configuredExtensionId}, then rerun: thinkrun setup`;
+        }
+        return 'Local bridge is unreachable. Start a Chromium-based browser with the ThinkRun extension active, then run thinkrun doctor again.';
+    }
+    if (bridgeRelevant) {
+        if (manifestIssue === 'inconsistent') {
+            return 'Local native-host manifests disagree across detected Chromium-based browsers. Run: thinkrun setup';
+        }
+        if (manifestIssue === 'parse_error' || manifestParseStatus === 'parse_error') {
+            return 'Local native-host manifest is unreadable. Run: thinkrun setup';
+        }
+        if (manifestIssue === 'missing') {
+            return 'Local native-host manifest is missing for a detected Chromium-based browser. Run: thinkrun setup';
+        }
+        if (manifestMismatch && extensionIdSource === 'default') {
+            return 'Local native-host manifest is registered for a different extension ID. If you are using the packaged ThinkRun extension, rerun: thinkrun setup\nIf you are using an unpacked/dev extension, copy its ID from chrome://extensions and run: thinkrun config set-extension-id <id>\nThen rerun: thinkrun setup';
+        }
+        if (manifestMismatch && configuredExtensionId) {
+            return `Local native-host manifest does not match ${configuredExtensionId}. Verify the installed ThinkRun extension ID in chrome://extensions, then rerun: thinkrun setup`;
+        }
+    }
+    if (!bridgeRelevant && activeCloudSessionId && !apiKey && !localEndpoint) {
+        return 'Set API key: thinkrun config set-key <key>';
+    }
+    if (bridgeRelevant && recoveryState === 'recovering') {
+        return 'Local bridge is reconnecting automatically. Wait a few seconds, then retry the local command.';
+    }
+    if (bridgeRelevant && extensionConnected === false) {
+        if (isCircuitBreakerTrip) {
+            return 'Local bridge is disconnected by the circuit breaker. Run: thinkrun reset-connection';
+        }
+        return 'Extension disconnected. Reload the ThinkRun extension in your Chromium-based browser, then run thinkrun doctor again.';
+    }
+    if (bridgeRelevant && !activeLocalTabId) {
+        return 'No active local tab. Run: thinkrun tabs\nThen: thinkrun attach <tabId>';
+    }
+    // Only prompt for API key when in cloud mode — local mode does not require one.
+    if (!apiKey && !localEndpoint && !bridgeRelevant) {
+        return 'Set API key: thinkrun config set-key <key>';
+    }
+    else if (!apiHealthOk && localEndpoint) {
+        return `Local endpoint is down. Start mech-browser-service or verify apiUrl/port.`;
+    }
+    else if (!apiHealthOk) {
+        return 'Cloud endpoint unreachable. Check network and apiUrl.';
+    }
+    else if (!activeCloudSessionId && !activeSessionId) {
+        if (localEndpoint) {
+            return 'No active session. Run: thinkrun cloud start\nIf server already has sessions: thinkrun cloud list -> thinkrun cloud use <sessionId>';
+        }
+        return 'No active session. Run: thinkrun cloud start';
+    }
+    else if (commandPathOk === false) {
+        return 'Command path is not ready. Run: thinkrun session debug for full routing details.';
+    }
+    else if (bridgeRelevant && activeLocalTabId) {
+        if (recoveryState === 'flapping') {
+            return 'Local bridge is flapping from repeated disconnects. Avoid patient retry loops; reload the ThinkRun extension or stabilize the page/browser before retrying.';
+        }
+        if (recoveryState === 'recently_recovered' || recoveryState === 'recovering') {
+            return 'Local bridge recently recovered from disconnect churn. If the next command still fails, retry once or run thinkrun session debug for live routing state.';
+        }
+        if ((recentDisconnectCount ?? 0) > 0) {
+            return 'Setup is usable, but the local bridge has been unstable recently. Try a safe read like: thinkrun snapshot';
+        }
+        return 'Setup looks good. Try: thinkrun navigate https://example.com';
+    }
+    else {
+        return 'Setup looks good. Try: thinkrun navigate https://example.com';
+    }
+}
+/** Check whether `bun` is available on PATH. */
+export function isBunAvailable() {
+    try {
+        execSync('bun --version', { stdio: 'ignore', timeout: 500 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Inspect daemon state for the doctor section.
+ * Only shown when localTransport=daemon OR daemon.json exists.
+ */
+export async function checkDaemonDoctor() {
+    const localTransport = config.get('localTransport') ?? 'native';
+    const daemonJsonPath = getDaemonJsonPath();
+    const daemonJsonExists = existsSync(daemonJsonPath);
+    const show = localTransport === 'daemon' || daemonJsonExists;
+    if (!show) {
+        return { show: false, status: 'down', bunMissing: false, flagOwnerMismatch: false };
+    }
+    const bunMissing = !isBunAvailable();
+    // Read raw config for owner + pid checks
+    let rawCfg = null;
+    if (daemonJsonExists) {
+        try {
+            rawCfg = JSON.parse(readFileSync(daemonJsonPath, 'utf-8'));
+        }
+        catch {
+            // unreadable
+        }
+    }
+    // Flag/owner mismatch: daemon.json says owner='native' but flag=daemon (or absent but flag=daemon)
+    const owner = rawCfg ? rawCfg.owner : undefined;
+    const flagOwnerMismatch = (localTransport === 'daemon' && owner === 'native') ||
+        (localTransport === 'native' && owner === 'daemon' && daemonJsonExists);
+    if (!daemonJsonExists || !rawCfg) {
+        return { show, status: 'down', bunMissing, flagOwnerMismatch };
+    }
+    const port = typeof rawCfg.port === 'number' ? rawCfg.port : undefined;
+    const pid = typeof rawCfg.pid === 'number' ? rawCfg.pid : undefined;
+    const protocolVersion = typeof rawCfg.protocolVersion === 'number' ? rawCfg.protocolVersion : undefined;
+    const binaryVersion = typeof rawCfg.binaryVersion === 'string' ? rawCfg.binaryVersion : undefined;
+    if (!port) {
+        return { show, status: 'down', bunMissing, flagOwnerMismatch };
+    }
+    // Stale-file detection: pid is recorded but the process is dead
+    if (typeof pid === 'number' && !isPidAlive(pid)) {
+        return { show, status: 'orphaned', port, pid, protocolVersion, binaryVersion, bunMissing, flagOwnerMismatch };
+    }
+    // Protocol version mismatch
+    if (typeof protocolVersion === 'number' && protocolVersion !== DAEMON_PROTOCOL_VERSION) {
+        return { show, status: 'mismatch', port, pid, protocolVersion, binaryVersion, bunMissing, flagOwnerMismatch };
+    }
+    // Health probe
+    const alive = await probeDaemonHealth(port);
+    if (!alive) {
+        const status = typeof pid === 'number' ? 'orphaned' : 'down';
+        return { show, status, port, pid, protocolVersion, binaryVersion, bunMissing, flagOwnerMismatch };
+    }
+    return { show, status: 'up', port, pid, protocolVersion, binaryVersion, bunMissing, flagOwnerMismatch };
+}
+export function getDoctorSessionDisplay(activeSessionId, sessionContext) {
+    try {
+        const context = sessionContext ?? getSessionContext();
+        if (context?.mode === 'local') {
+            return {
+                activeLocalTab: context.tabId,
+                activeCloudSession: '(none)',
+                activeSessionSummary: `local tab ${context.tabId}`,
+            };
+        }
+        if (context?.mode === 'cloud') {
+            return {
+                activeLocalTab: '(none)',
+                activeCloudSession: context.sessionId,
+                activeSessionSummary: `cloud session ${context.sessionId}`,
+            };
+        }
+    }
+    catch {
+        // Fall back to the raw activeSessionId display when the stored context is mixed or invalid.
+    }
+    return {
+        activeLocalTab: '(none)',
+        activeCloudSession: '(none)',
+        activeSessionSummary: activeSessionId || '(none)',
+    };
+}
+export function createDoctorCommand() {
+    return new Command('doctor')
+        .description('Diagnose endpoint, auth, and session setup')
+        .option('--full', 'Run full checks including remote checksum verification')
+        .option('--offline', 'Skip network checks (API health / key acceptance ping)')
+        .action(async (opts) => {
+        const apiUrl = config.get('apiUrl') || 'https://api.thinkbrowse.io';
+        const apiKey = config.get('apiKey');
+        const activeSessionId = config.get('activeSessionId');
+        const localEndpoint = isLocalApiUrl(apiUrl);
+        const bridgePort = readBridgePort();
+        const bridgeUrl = `http://127.0.0.1:${bridgePort}`;
+        const portFileMtime = getBridgePortFileMtimeMs();
+        const stalePortFileMs = 5 * 60 * 1000;
+        const nowMs = Date.now();
+        let sessionContext;
+        try {
+            sessionContext = getSessionContext();
+        }
+        catch {
+            sessionContext = undefined;
+        }
+        const sessionDisplay = getDoctorSessionDisplay(activeSessionId, sessionContext);
+        const registeredExtensionId = config.get('registeredExtensionId');
+        const preferPackagedDefaultExtensionId = config.get('preferPackagedDefaultExtensionId') === true;
+        const [apiHealth, bridgeHealth, resolution, nativeHost, daemonDoctor] = await Promise.all([
+            opts.offline
+                ? Promise.resolve({ ok: true, message: 'skipped (--offline)' })
+                : checkHealth(apiUrl, apiKey),
+            checkHealth(bridgeUrl),
+            getResolutionInfo(),
+            checkNativeHost({ verifyChecksum: opts.full ?? false }),
+            checkDaemonDoctor(),
+        ]);
+        const doctorExtensionId = resolveDoctorExtensionId({
+            resolvedExtensionId: resolveExtensionId(),
+            registeredExtensionId,
+            preferPackagedDefaultExtensionId,
+            manifestExtensionIds: nativeHost.manifestExtensionIds,
+            manifestParseStatus: nativeHost.manifestParseStatus,
+            manifestExists: nativeHost.manifestExists,
+        });
+        const effectiveExtensionId = doctorExtensionId.extensionId;
+        const extensionIdSource = doctorExtensionId.source;
+        const manifestIssue = nativeHost.binaryExists
+            ? getManifestRegistrationIssue({
+                manifestEntries: nativeHost.manifestEntries,
+                manifestExtensionIds: nativeHost.manifestExtensionIds,
+                registeredExtensionId,
+                effectiveExtensionId,
+            })
+            : null;
+        const manifestMismatch = nativeHost.binaryExists ? manifestIssue !== null : false;
+        const commandPathOk = resolution.resolvedMode !== null;
+        console.log(chalk.bold('ThinkRun Doctor'));
+        console.log('');
+        console.log('  API URL:       ', chalk.cyan(apiUrl), localEndpoint ? chalk.gray('(local)') : chalk.gray('(cloud)'));
+        console.log('  API Key:       ', chalk.cyan(config.maskApiKey(apiKey)));
+        console.log('  Active Local Tab:', chalk.cyan(sessionDisplay.activeLocalTab));
+        console.log('  Cloud Session:  ', chalk.cyan(sessionDisplay.activeCloudSession));
+        console.log('  Session Target: ', chalk.cyan(sessionDisplay.activeSessionSummary));
+        console.log('  Bridge Port:   ', chalk.cyan(String(bridgePort)));
+        console.log('  Local Transport:', chalk.cyan(config.get('localTransport') ?? 'native'), chalk.gray('(native=default)'));
+        const distinctManifestExtensionIds = Array.isArray(nativeHost.manifestExtensionIds)
+            ? Array.from(new Set(nativeHost.manifestExtensionIds))
+            : [];
+        const registeredSourceFromReadableManifest = extensionIdSource === 'registered' &&
+            nativeHost.manifestParseStatus === 'parsed' &&
+            distinctManifestExtensionIds.length === 1 &&
+            distinctManifestExtensionIds[0] === effectiveExtensionId;
+        const extensionIdSourceLabel = extensionIdSource === 'config'
+            ? '(configured)'
+            : extensionIdSource === 'registered'
+                ? registeredSourceFromReadableManifest
+                    ? '(registered manifest ID)'
+                    : '(cached registered ID)'
+                : extensionIdSource === 'env'
+                    ? '(env override)'
+                    : extensionIdSource === 'flag'
+                        ? '(command override)'
+                        : '(default packaged ID)';
+        console.log('  Extension ID:  ', chalk.cyan(effectiveExtensionId), chalk.gray(extensionIdSourceLabel));
+        if (Array.isArray(nativeHost.manifestExtensionIds) && nativeHost.manifestExtensionIds.length > 0) {
+            console.log('  Manifest IDs:  ', chalk.cyan(nativeHost.manifestExtensionIds.join(', ')));
+        }
+        if (isValidExtensionId(registeredExtensionId) && registeredExtensionId !== effectiveExtensionId) {
+            console.log('  Registered ID: ', chalk.cyan(registeredExtensionId), chalk.gray('(last successful local registration)'));
+        }
+        console.log('');
+        // --- API key health (PRD 0086 B4) ---
+        console.log('API Key:');
+        const keyHealth = config.getKeyHealth();
+        if (keyHealth.state === 'missing') {
+            console.log(`  ${chalk.red('✗')} Key: not configured`);
+            console.log(`    Run: ${chalk.cyan('thinkrun config set-key <your-api-key>')}`);
+        }
+        else if (keyHealth.state === 'malformed') {
+            console.log(`  ${chalk.red('✗')} Key: quarantined malformed value (${keyHealth.quarantinedMasked})`);
+            console.log(`    The stored key failed validation — it may have been overwritten (e.g. browser autofill).`);
+            console.log(`    Run: ${chalk.cyan('thinkrun config set-key <your-api-key>')}`);
+        }
+        else {
+            const shapeNote = keyHealth.shapeValid === false
+                ? ` ${chalk.yellow('(unrecognized shape — saved with --force?)')}`
+                : '';
+            console.log(`  ${chalk.green('✓')} Key: ${keyHealth.maskedKey}${shapeNote}`);
+            if (opts.offline) {
+                console.log(`  ${chalk.gray('-')} Server acceptance: skipped (--offline)`);
+            }
+            else {
+                // checkHealth already performed the authenticated ping with this key.
+                console.log(`  ${apiHealth.ok ? chalk.green('✓') : chalk.red('✗')} Server acceptance: ${apiHealth.ok ? 'accepted' : `rejected — ${apiHealth.message}`}`);
+            }
+        }
+        console.log('');
+        console.log('Checks:');
+        console.log(`  ${apiHealth.ok ? chalk.green('✓') : chalk.red('✗')} API health:    ${apiHealth.message}`);
+        const bridgeNote = localEndpoint ? '' : chalk.gray(' (local only)');
+        console.log(`  ${bridgeHealth.ok ? chalk.green('✓') : chalk.red('✗')} Bridge health: ${bridgeHealth.message}${bridgeNote}`);
+        const bridgeRelevant = resolution.contextMode === 'local' ||
+            resolution.resolvedMode === 'local';
+        // Only show extension recovery hints when the CLI is actually trying to use
+        // local browser context. In cloud mode, the bridge row is labelled "(local only)"
+        // and extension guidance would distract from the real diagnosis.
+        if (bridgeRelevant) {
+            const extensionHint = getExtensionDisconnectHint(bridgeHealth);
+            if (extensionHint !== null) {
+                console.log(`         ${chalk.yellow('→')} ${extensionHint}`);
+            }
+        }
+        console.log(`  ${commandPathOk ? chalk.green('✓') : chalk.red('✗')} Command path:  ${commandPathOk ? `routes to ${resolution.resolvedMode}` : resolution.error ?? 'would fail'}`);
+        const stalePortAgeMs = getStaleBridgePortFileAgeMs(portFileMtime, { nowMs, maxAgeMs: stalePortFileMs });
+        if (stalePortAgeMs !== null) {
+            const ageMin = Math.max(1, Math.round(stalePortAgeMs / 60_000));
+            console.log('');
+            console.log(chalk.yellow('Note:'), `~/.thinkbrowse/port was last written about ${ageMin} minute(s) ago. After a native-host restart or port rotation, reload the ThinkRun extension (or re-open the browser) so the file matches the live bridge, then run doctor again.`);
+        }
+        console.log('');
+        console.log('Suggested next step:');
+        const suggestion = getSuggestedNextStep({
+            apiKey,
+            localEndpoint,
+            apiHealthOk: apiHealth.ok,
+            activeLocalTabId: sessionContext?.mode === 'local' ? sessionContext.tabId : undefined,
+            activeCloudSessionId: sessionContext?.mode === 'cloud' ? sessionContext.sessionId : undefined,
+            activeSessionId,
+            bridgeRelevant,
+            bridgeHealthOk: bridgeHealth.ok,
+            commandPathOk,
+            extensionConnected: bridgeHealth.extensionConnected,
+            isCircuitBreakerTrip: bridgeHealth.isCircuitBreakerTrip,
+            recoveryState: bridgeHealth.recoveryState,
+            recentDisconnectCount: bridgeHealth.recentDisconnectCount,
+            configuredExtensionId: effectiveExtensionId,
+            extensionIdSource,
+            manifestMismatch,
+            manifestIssue,
+            manifestParseStatus: nativeHost.manifestParseStatus,
+        });
+        for (const line of suggestion.split('\n')) {
+            console.log(`  - ${line}`);
+        }
+        if (!commandPathOk && resolution.error) {
+            console.log('');
+            console.log(chalk.yellow('  Run') + ' thinkrun session debug' + chalk.yellow(' for full routing details.'));
+        }
+        // --- Native Host section ---
+        console.log('');
+        console.log('Native Host:');
+        console.log(`  Platform:   ${nativeHost.platform}`);
+        if (!nativeHost.binaryExists) {
+            console.log(`  ${chalk.red('✗')} Binary:   not found`);
+            console.log(`    Run: ${chalk.cyan('thinkrun setup')}`);
+            console.log(`    (If you installed via ${chalk.cyan('bun install -g')}, Bun blocks postinstall scripts — ${chalk.cyan('thinkrun setup')} installs the binary manually)`);
+        }
+        else {
+            const versionLabel = nativeHost.installedVersion
+                ? nativeHost.versionMatch
+                    ? `v${nativeHost.installedVersion}`
+                    : `v${nativeHost.installedVersion} ${chalk.yellow(`(outdated — expected v${nativeHost.expectedVersion})`)}`
+                : 'unknown version';
+            console.log(`  ${nativeHost.versionMatch ? chalk.green('✓') : chalk.yellow('!')} Binary:   ${nativeHost.binaryPath} (${versionLabel})`);
+            if (nativeHost.checksumVerified === true) {
+                console.log(`  ${chalk.green('✓')} Checksum: verified`);
+            }
+            else if (nativeHost.checksumVerified === false) {
+                console.log(`  ${chalk.red('✗')} Checksum: mismatch`);
+            }
+            else {
+                const checksumNote = opts.full ? 'could not verify (offline?)' : 'not checked (run with --full to verify)';
+                console.log(`  ${chalk.gray('-')} Checksum: ${checksumNote}`);
+            }
+            if (process.platform === 'win32') {
+                console.log(`  ${chalk.gray('-')} Manifest: N/A (Windows — registry-based)`);
+            }
+            else {
+                if (manifestIssue === 'parse_error' || nativeHost.manifestParseStatus === 'parse_error') {
+                    console.log(`  ${chalk.red('✗')} Manifest: unreadable (${nativeHost.manifestParseError ?? 'could not read native messaging manifest'})`);
+                    console.log(`    Run: ${chalk.cyan('thinkrun setup')}`);
+                }
+                else if (manifestIssue === 'missing') {
+                    console.log(`  ${chalk.red('✗')} Manifest: missing for at least one detected Chromium-based browser`);
+                    console.log(`    Run: ${chalk.cyan('thinkrun setup')}`);
+                }
+                else if (manifestIssue === 'inconsistent') {
+                    console.log(`  ${chalk.yellow('!')} Manifest: detected browser registrations are inconsistent for extension ID ${effectiveExtensionId}`);
+                    console.log(`    Run: ${chalk.cyan('thinkrun setup')}`);
+                }
+                else if (manifestIssue === 'wrong_id') {
+                    console.log(`  ${chalk.yellow('!')} Manifest: detected browser registrations disagree with extension ID ${effectiveExtensionId}`);
+                    console.log(`    Run: ${chalk.cyan('thinkrun setup')}`);
+                }
+                else {
+                    console.log(`  ${nativeHost.manifestExists ? chalk.green('✓') : chalk.red('✗')} Manifest: ${nativeHost.manifestExists ? 'registered' : `not found at ${nativeHost.manifestPath}`}`);
+                }
+                if (nativeHost.manifestExtensionIds && nativeHost.manifestExtensionIds.length > 0) {
+                    console.log(`  ${chalk.gray('-')} Allowed IDs: ${nativeHost.manifestExtensionIds.join(', ')}`);
+                    if (manifestIssue === 'wrong_id' || manifestIssue === 'inconsistent') {
+                        console.log(`  ${chalk.yellow('!')} Manifest/CLI mismatch: doctor expects ${effectiveExtensionId}. Re-run ${chalk.cyan('thinkrun setup')} after setting the correct extension ID.`);
+                    }
+                }
+            }
+            if (!nativeHost.versionMatch) {
+                console.log(`    Run: ${chalk.cyan('thinkrun setup --force')}`);
+            }
+            if (extensionIdSource === 'default') {
+                console.log(`    Using packaged extension ID fallback. For unpacked/dev installs, run: ${chalk.cyan('thinkrun config set-extension-id <id>')}`);
+            }
+        }
+        // --- Daemon section (PRD 0086 task 4.7) ---
+        // Show when localTransport=daemon or daemon.json exists on disk.
+        if (daemonDoctor.show) {
+            console.log('');
+            console.log('Daemon:');
+            const localTransport = config.get('localTransport') ?? 'native';
+            console.log(`  Transport flag: ${chalk.cyan(localTransport)}`);
+            if (daemonDoctor.flagOwnerMismatch) {
+                console.log(`  ${chalk.yellow('!')} Flag/owner mismatch: localTransport=${localTransport} but daemon.json owner differs.`);
+                console.log(`    Set consistently: ${chalk.cyan('thinkrun config set localTransport native')} (or daemon)`);
+            }
+            switch (daemonDoctor.status) {
+                case 'up':
+                    console.log(`  ${chalk.green('✓')} Status: up (port=${daemonDoctor.port}, pid=${daemonDoctor.pid ?? 'unknown'})`);
+                    if (daemonDoctor.protocolVersion !== undefined) {
+                        const vMatch = daemonDoctor.protocolVersion === DAEMON_PROTOCOL_VERSION;
+                        console.log(`  ${vMatch ? chalk.green('✓') : chalk.yellow('!')} Protocol version: ${daemonDoctor.protocolVersion}${vMatch ? '' : ` ${chalk.yellow(`(expected ${DAEMON_PROTOCOL_VERSION})`)}`}`);
+                    }
+                    if (daemonDoctor.binaryVersion) {
+                        console.log(`  ${chalk.gray('-')} Daemon version: ${daemonDoctor.binaryVersion}`);
+                    }
+                    break;
+                case 'down':
+                    console.log(`  ${chalk.red('✗')} Status: down (daemon.json absent or unreadable)`);
+                    if (localTransport === 'daemon') {
+                        console.log(`    To start: set THINKRUN_DAEMON_SPIKE=1 (THINKBROWSE_DAEMON_SPIKE also works), then run a local command`);
+                    }
+                    break;
+                case 'orphaned':
+                    console.log(`  ${chalk.yellow('!')} Status: orphaned (port=${daemonDoctor.port ?? '?'}, pid=${daemonDoctor.pid ?? '?'} — process dead)`);
+                    console.log(`    daemon.json is stale. It will be cleaned up on next daemon start.`);
+                    break;
+                case 'mismatch':
+                    console.log(`  ${chalk.yellow('!')} Status: protocol version mismatch (daemon=${daemonDoctor.protocolVersion ?? '?'}, expected=${DAEMON_PROTOCOL_VERSION})`);
+                    console.log(`    Update the thinkrun CLI package to resolve the mismatch.`);
+                    break;
+            }
+            if (daemonDoctor.bunMissing) {
+                console.log(`  ${chalk.yellow('!')} bun not found on PATH — daemon requires bun (packaging TODO: task 4.2)`);
+                console.log(`    Install bun: https://bun.sh`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=doctor.js.map