elanous 0.2.0 → 0.2.5

package/src/cli/doctor-cli.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
 import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir, tmpdir } from 'node:os';
@@ -7,7 +8,8 @@ import { fileURLToPath } from 'node:url';
 import type { Command } from 'commander';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { discoverChromeBinary } from '../browser-cdp/client.js';
-import { listProviders } from '../oauth/store.js';
+import { resolveUsableLlm, type UsableLlm } from '../llm/usable-llm.js';
+import { detectLocale } from '../expression/locale.js';
 import { findRetiredConfigKeysInFile, getUserConfig, type RetiredConfigKey, type UserConfig } from '../user-config.js';
 import { codeRevision } from '../version/code-revision.js';
 import {
@@ -26,8 +28,11 @@ import {
   type SubstrateSignals,
 } from './doctor-readiness.js';
 import { debug } from '../debug/log.js';
-import { applyDoctorFixes, applyServiceRestart, applySudoFixes, planDoctorFixes, type DoctorFixDeps } from './doctor-fix.js';
-import { detectDistroFamily } from './doctor-distro.js';
+import { resolveDaemonEndpoint, type ResolveDaemonEndpointOpts } from '../nexus/daemon-endpoint.js';
+import { applyDoctorFixes, applyGitInstall, applyServiceRestart, applySudoFixes, planDoctorFixes, type DoctorFixDeps, type DoctorFixItem } from './doctor-fix.js';
+import { ADVISABLE_DOCTOR_FIX_IDS, adviseDoctorFixes, type DoctorAdvice } from './doctor-llm-assist.js';
+import { gitInstallPlan } from './git-install-plan.js';
+import { detectDistroFamily, parseOsRelease } from './doctor-distro.js';
 import { checkPythonEnv } from './python-cli.js';
 
 function defaultCheckPythonEnv(): { status: 'ok' | 'fixable' | 'manual'; evidence: string; remedy?: string } {
@@ -92,6 +97,7 @@ export interface DoctorReport {
   ok: boolean;
   credentials: DoctorCredential[];
   externalCommands: DoctorExternalCommand[];
+  requiredMissing?: string[];
   capabilitySummary?: DoctorCapabilitySummary;
   /** F1 readiness. Present on a successful report. Absent when the report itself failed. */
   readiness?: ReadinessReport;
@@ -121,6 +127,8 @@ export interface DoctorOptions {
   readFile?: (path: string) => string;
   exists?: (path: string) => boolean;
   commandExists?: (name: string) => boolean;
+  /** Whether this process runs as root (uid 0) — git install then skips sudo. Test seam. */
+  isRoot?: boolean;
   discoverChromeBinary?: () => string | null;
   loadNativeModule?: (name: string) => boolean;
   resolveNativeModuleDir?: (name: string) => string | null;
@@ -134,12 +142,15 @@ export interface DoctorOptions {
    */
   readiness?: ReadinessDeps;
   checkReadiness?: (deps: ReadinessDeps) => ReadinessReport;
-  /** Read-only auth-store provider names. Values are never requested. */
+  resolveLlm?: () => UsableLlm;
+  /** Legacy read-only seam; route selection no longer uses provider-name presence. */
   listAuthProviders?: () => readonly string[];
   /** Read-only `codeRevision()`. */
   codeRevision?: () => string | undefined;
   /** Read-only `GET /v1/health`. `null` means no response. */
   fetchHealth?: () => { daemonSha?: string } | null;
+  /** Test seam — daemon address. `null` means this universe has no daemon (do not guess a port). */
+  resolveDaemonEndpoint?: (opts?: ResolveDaemonEndpointOpts) => { healthUrl: string } | null;
   /**
    * Read-only install prefix. `null` means a checkout was confirmed.
    * Throw when the lookup itself fails — that is not a checkout.
@@ -155,7 +166,11 @@ export interface DoctorOptions {
   ghVersion?: () => string | null;
 }
 
-export interface DoctorCliDeps extends DoctorOptions, Pick<DoctorFixDeps, 'home' | 'readdir' | 'appendFile' | 'writeFile' | 'mkdir' | 'lstat' | 'chmod' | 'rename' | 'remove' | 'temporaryPath'> {
+export interface DoctorCliDeps extends DoctorOptions, Pick<DoctorFixDeps, 'home' | 'readdir' | 'appendFile' | 'writeFile' | 'mkdir' | 'lstat' | 'chmod' | 'rename' | 'remove' | 'temporaryPath' | 'installStaticTool' | 'smokeCheck' | 'pythonSetup' | 'recheckPythonEnv'> {
+  /** Git install-only seams; all other doctor repairs retain their existing consent rules. */
+  gitInteractive?: boolean;
+  confirmGitInstall?: (display: string) => Promise<boolean>;
+  runGitInstallCommand?: (command: string, args: readonly string[]) => { status: number | null };
   out?: { log: (value: string) => void };
   err?: { error: (value: string) => void };
   setExitCode?: (code: number) => void;
@@ -163,20 +178,15 @@ export interface DoctorCliDeps extends DoctorOptions, Pick<DoctorFixDeps, 'home'
   applySudoFixes?: typeof applySudoFixes;
   /** D5 시험 seam — `--restart` 실행기. */
   applyServiceRestart?: typeof applyServiceRestart;
+  /** Read-only advice call; injection avoids any real LLM access in tests. */
+  adviseLlm?: (prompt: string, provider: string, model: string) => Promise<string>;
+  resolveAdviceProvider?: (config: UserConfig) => { provider: string; model: string; auth: string };
+  confirmAdvice?: (message: string) => Promise<boolean>;
+  adviceInteractive?: boolean;
 }
 
 const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 const tavilyNames = new Set(['TAVILY_API_KEY', 'TAVILY_KEY']);
-const HEALTH_URL = 'http://127.0.0.1:31415/v1/health';
-
-function codexLoginPresent(providers: readonly string[]): boolean {
-  return providers.some((name) => name === 'openai-codex' || name.startsWith('openai-codex:'));
-}
-
-/** Presence only. Token strings from the auth store never leave this function. */
-function defaultListAuthProviders(): readonly string[] {
-  return listProviders();
-}
 
 function defaultCodeRevision(): string | undefined {
   try {
@@ -186,8 +196,17 @@ function defaultCodeRevision(): string | undefined {
   }
 }
 
-function defaultFetchHealth(): { daemonSha?: string } | null {
-  const probe = spawnSync('curl', ['-fsS', '--max-time', '2', HEALTH_URL], {
+/** Test seam — records the curl argv `defaultFetchHealth` actually runs. */
+let fetchHealthSpawn: typeof spawnSync = spawnSync;
+
+export function setFetchHealthSpawnForTest(spawn: typeof spawnSync | null): void {
+  fetchHealthSpawn = spawn ?? spawnSync;
+}
+
+function defaultFetchHealth(resolveEndpoint: (opts?: ResolveDaemonEndpointOpts) => { healthUrl: string } | null = resolveDaemonEndpoint): { daemonSha?: string } | null {
+  const healthUrl = resolveEndpoint()?.healthUrl;
+  if (!healthUrl) return null;
+  const probe = fetchHealthSpawn('curl', ['-fsS', '--max-time', '2', healthUrl], {
     encoding: 'utf8',
     timeout: 3000,
     stdio: ['ignore', 'pipe', 'ignore'],
@@ -267,7 +286,6 @@ interface ReadinessLookup {
   platform: NodeJS.Platform;
   commandExists: (name: string) => boolean;
   getConfig: () => UserConfig;
-  listAuthProviders: () => readonly string[];
   codeRevision: () => string | undefined;
   fetchHealth: () => { daemonSha?: string } | null;
   readInstallPrefix: () => string | null | undefined;
@@ -279,8 +297,6 @@ interface ReadinessLookup {
   /** 저장소가 시험한 bun 판(`.bun-version`) · 지금 도는 bun 판(시험 seam). */
   bunPin?: () => string | null;
   bunVersion?: () => string | null;
-  /** LLM 키가 하나라도 풀렸나(자격 보고서에서 · 없으면 못 쟀다). */
-  llmKeyResolved?: boolean;
   /** `/etc/os-release` 본문(시험 seam) — 못 읽으면 null. */
   readOsRelease?: () => string | null;
   /** 빌드 도구 탐침(시험 seam). */
@@ -344,19 +360,6 @@ function resolveReadinessDeps(lookup: ReadinessLookup): ReadinessDeps {
   if (provider !== null && provider !== 'auto' && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(provider)) {
     provider = null;
   }
-  let codexLogin: boolean | null = null;
-  let anyLogin: boolean | null = null;
-  try {
-    const providers = lookup.listAuthProviders();
-    codexLogin = codexLoginPresent(providers);
-    anyLogin = providers.length > 0;
-  } catch {
-    codexLogin = null;
-  }
-  // 로그인이 있거나 LLM 키가 풀렸으면 true · 둘 다 «아니라고 잰» 경우만 false · 하나라도 못 쟀으면 null.
-  const llmCredentialAvailable = anyLogin === true || lookup.llmKeyResolved === true
-    ? true
-    : anyLogin === false && lookup.llmKeyResolved === false ? false : null;
   const pathEntries = (lookup.env.PATH ?? '').split(lookup.pathDelimiter).filter((entry) => entry.length > 0);
   let ghOnPath: boolean | null = null;
   let ghAuthStatus: number | null = null;
@@ -439,8 +442,6 @@ function resolveReadinessDeps(lookup: ReadinessLookup): ReadinessDeps {
   }
   return {
     provider,
-    codexLogin,
-    llmCredentialAvailable,
     ghOnPath,
     ghAuthStatus,
     ghVersion,
@@ -925,6 +926,28 @@ export function summarizeDoctorCapabilities(credentials: readonly DoctorCredenti
   return { available, unavailable, unknownCredentials };
 }
 
+function gitPlanFor(options: DoctorOptions) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const exists = options.exists ?? existsSync;
+  const has = options.commandExists ?? ((name: string) => {
+    const extensions = platform === 'win32'
+      ? (env.PATHEXT?.split(';').filter(Boolean).map((extension) => extension.toLowerCase()) ?? ['.com', '.exe', '.bat', '.cmd'])
+      : [''];
+    return (env.PATH ?? '').split(options.pathDelimiter ?? delimiter).some((dir) =>
+      dir.length > 0 && extensions.some((extension) => exists(join(dir, `${name}${extension}`))));
+  });
+  let distro: string | undefined = options.readiness?.distro;
+  if (platform === 'linux' && (!distro || distro === 'unknown')) {
+    try {
+      const fields = parseOsRelease((options.readFile ?? ((path) => readFileSync(path, 'utf8')))('/etc/os-release'));
+      distro = fields.ID?.toLowerCase();
+      if (!distro || distro === 'unknown') distro = detectDistroFamily(platform, `ID_LIKE=${fields.ID_LIKE ?? ''}`);
+    } catch { distro = undefined; }
+  }
+  return gitInstallPlan({ platform, distro, has, isRoot: options.isRoot ?? (typeof process.getuid === 'function' && process.getuid() === 0) });
+}
+
 export function runDoctor(options: DoctorOptions = {}): DoctorReport {
   const root = options.repositoryRoot ?? repositoryRoot;
   const env = options.env ?? process.env;
@@ -983,6 +1006,11 @@ export function runDoctor(options: DoctorOptions = {}): DoctorReport {
         .find((candidate): candidate is { name: string; source: Exclude<CredentialSource, 'unresolved'> } => candidate.source !== 'unresolved');
       if (sibling) credential.satisfiedBy = sibling;
     }
+    const requiredMissing = externalCommands.commands
+      .filter((command) => command.tier === 'required' && (command.status === 'missing' || command.status === 'broken'))
+      .map((command) => command.name);
+    const missingGit = externalCommands.commands.find((command) => command.name === 'git' && command.status === 'missing');
+    if (missingGit) missingGit.fix = gitPlanFor(options).display;
     const evaluateReadiness = options.checkReadiness ?? checkReadiness;
     const readiness = options.readiness !== undefined
       ? options.readiness
@@ -991,25 +1019,30 @@ export function runDoctor(options: DoctorOptions = {}): DoctorReport {
         pathDelimiter,
         platform,
         commandExists,
-        getConfig,
-        listAuthProviders: options.listAuthProviders ?? defaultListAuthProviders,
+        getConfig: () => resolutionOptions.userConfig,
         codeRevision: options.codeRevision ?? defaultCodeRevision,
-        fetchHealth: options.fetchHealth ?? defaultFetchHealth,
+        fetchHealth: options.fetchHealth ?? (() => defaultFetchHealth(options.resolveDaemonEndpoint ?? resolveDaemonEndpoint)),
         readInstallPrefix: options.readInstallPrefix ?? (() => defaultReadInstallPrefix(root, exists)),
         bunPin: options.bunPin ?? (() => readBunPin(root)),
         ghAuthStatus: options.ghAuthStatus ?? (() => defaultGhAuthStatus(commandExists)),
         ghVersion: options.ghVersion ?? (() => defaultGhVersion(commandExists)),
         tmpdirSameFsAsBunCache: options.tmpdirSameFsAsBunCache ?? (() => defaultTmpdirSameFsAsBunCache(env)),
-        llmKeyResolved: llmKeyResolvedFrom(credentials),
         nodePty: nodePtyStatus(externalCommands.commands),
         ...(options.probeBuildToolchain ? { probeBuildToolchain: options.probeBuildToolchain } : {}),
         ...(options.checkPythonEnv ? { checkPythonEnv: options.checkPythonEnv } : {}),
         ...(options.probeHostEnvironment ? { probeHostEnvironment: options.probeHostEnvironment } : {}),
       });
+    // An injected readiness snapshot stays as-is. For a real machine, measure the
+    // same runtime route as `start` rather than inferring usability from key names.
+    if (options.readiness === undefined && readiness.provider !== null) {
+      try { readiness.usableLlm = options.resolveLlm ? options.resolveLlm() : resolveUsableLlm({ config: resolutionOptions.userConfig }); }
+      catch { readiness.usableLlm = null; }
+    }
     return {
       ok: true,
       credentials,
       externalCommands: externalCommands.commands,
+      requiredMissing,
       capabilitySummary: summarizeDoctorCapabilities(credentials),
       readiness: evaluateReadiness(readiness),
       retiredConfigKeys: findRetiredConfigKeysInFile(options.configPath, readFile),
@@ -1028,62 +1061,140 @@ function formatReadiness(readiness: ReadinessReport | undefined): string[] {
   if (readiness === undefined) return [];
   const todo = readiness.items.filter((entry) => entry.status === 'manual' || entry.status === 'fixable');
   return [
-    '준비 상태:',
+    'Readiness:',
     ...readiness.items.map((entry) => {
       const remedy = entry.remedy === undefined ? '' : ` — ${entry.remedy}`;
       return `  ${entry.id}: ${entry.status} — ${entry.evidence}${remedy}`;
     }),
     todo.length === 0
-      ? '할 일 없음.'
-      // 처방은 줄마다 이미 있다 — 「fixable」이 곧 `doctor --fix` 는 아니다(install-path 의 처방은 export 한 줄).
-      : `할 일 ${todo.length}개: ${todo.map((entry) => entry.id).join(', ')} — 처방은 위 각 줄 끝`,
+      ? 'Nothing to do.'
+      : `To do (${todo.length}): ${todo.map((entry) => entry.id).join(', ')} — each line above ends with its fix`,
   ];
 }
 
+function humanFreeFallback(value: string): string {
+  return value.replace(/\s+/g, ' ')
+    .split(/\b(?:MEASURED|CHANGED)\s*(?::|\d{4}-\d{2}-\d{2})/i, 1)[0]!
+    .replace(/\(📏[^)]*\)/g, '')
+    .replace(/\s*[—–·]\s*(?:src|skills|scripts|catalog|test)\/.*$/g, '')
+    .replace(/\([^)]*\b(?:src|skills|scripts|catalog|test)\/[\w./:-]+[^)]*\)/g, '')
+    .replace(/\b(?:src|skills|scripts|catalog|test)\/[\w./:-]+|\b[\w-]+\.ts(?::\d+)?/g, '')
+    .replace(/\s{2,}/g, ' ').trim().replace(/[—–·;,\s]+$/, '');
+}
+
+export function humanBreaks(value: string): string | undefined {
+  if (value.trim().toLowerCase() === 'unmeasured'
+    || /\b\d+ test (failures|errors)\b|\bmeasured\b|\bpostmortem\b|\bquota\b/i.test(value)
+    || /[가-힣ㄱ-ㅎㅏ-ㅣ]/.test(value)) return undefined;
+  return humanFreeFallback(value) || undefined;
+}
+
 function formatCapabilitySummary(summary: DoctorCapabilitySummary): string[] {
   const unavailable = summary.unavailable.map((capability) =>
-    `  ${capability.name} — unlock with ${capability.credential}${capability.freeFallback !== undefined ? `; free alternative: ${capability.freeFallback}` : ''}`,
+    `  ${capability.name} — unlock with ${capability.credential}${capability.freeFallback !== undefined && humanFreeFallback(capability.freeFallback) ? `; free alternative: ${humanFreeFallback(capability.freeFallback)}` : ''}`,
   );
   return [
-    '할 수 있는 일:',
+    'Available:',
     ...(summary.available.length === 0 ? ['  None.'] : summary.available.map((capability) => `  ${capability.name} — unlocked by ${capability.credential}`)),
-    '못 하는 일:',
+    'Unavailable:',
     ...(unavailable.length === 0 ? ['  None.'] : unavailable),
     'Unknown by credential:',
     ...(summary.unknownCredentials.length === 0 ? ['  Empty.'] : summary.unknownCredentials.map((credential) => `  ${credential}`)),
   ];
 }
 
-export function formatDoctorReport(report: DoctorReport): string {
+export function formatDoctorReport(report: DoctorReport, options: { credentials?: boolean } = {}): string {
   if (!report.ok) return `Doctor failed: ${report.reason ?? 'unknown error'}`;
   const capabilitySummary = report.capabilitySummary ?? summarizeDoctorCapabilities(report.credentials);
+  const requiredMissing = report.requiredMissing ?? report.externalCommands
+    .filter((command) => command.tier === 'required' && (command.status === 'missing' || command.status === 'broken'))
+    .map((command) => command.name);
+  const resolved = report.credentials.filter((credential) => credential.resolved).length;
+  const satisfied = report.credentials.filter((credential) => !credential.resolved && credential.satisfiedBy !== undefined).length;
   return [
-    ...report.credentials.map((credential) => [
+    ...formatReadiness(report.readiness),
+    ...(requiredMissing.length ? [`⛔ Required commands missing: ${requiredMissing.join(', ')}`] : []),
+    `Credentials: ${resolved}/${report.credentials.length} resolved${satisfied ? ` · ${satisfied} satisfied by alternative names` : ''} · details: elanous doctor --credentials`,
+    ...(options.credentials ? report.credentials.map((credential) => [
       `${credential.name}: ${credential.resolved ? 'resolved' : 'unresolved'} (${credential.source}) — ${credential.note}`,
       ...(credential.satisfiedBy !== undefined ? [`  Satisfied by: ${credential.satisfiedBy.name} (${credential.satisfiedBy.source})`] : []),
       ...(credential.requiredFor !== undefined ? [`  Required for: ${credential.requiredFor.join(', ')}`] : []),
-      ...(credential.freeFallback !== undefined ? [`  Free fallback${credential.freeFallbackMode === 'auto' || credential.freeFallbackMode === 'manual' || credential.freeFallbackMode === 'none' ? ` [${credential.freeFallbackMode}]` : ''}: ${credential.freeFallback}`] : []),
-    ].join('\n')),
+      ...(credential.freeFallback !== undefined ? [`  Free fallback${credential.freeFallbackMode === 'auto' || credential.freeFallbackMode === 'manual' || credential.freeFallbackMode === 'none' ? ` [${credential.freeFallbackMode}]` : ''}: ${humanFreeFallback(credential.freeFallback)}`] : []),
+    ].join('\n')) : []),
     ...(report.catalogMetadataUnavailable ? ['Catalog metadata unavailable: could not read catalog/resources.yaml.'] : []),
-    ...(report.retiredConfigKeys ?? []).map(({ path, reason }) => `더는 안 쓰는 설정 키: ${path} — ${reason}`),
+    ...(report.retiredConfigKeys ?? []).map(({ path, reason }) => `Retired config key: ${path} — ${reason}`),
     'External commands:',
     ...report.externalCommands.map((command) => {
       const breaks = command.status === 'broken' ? command.breaks_broken ?? command.breaks : command.breaks;
+      const visibleBreaks = breaks === undefined ? undefined : humanBreaks(breaks);
       const fix = command.status === 'broken' ? command.fix_broken ?? command.fix : command.fix;
       return [
         `${command.name}: ${command.status === 'skipped' ? `skipped (${command.platform}-only)` : `${command.status} (${command.tier})`}${command.detail === undefined ? '' : ` — ${command.detail}`}`,
-        ...((command.status === 'missing' || command.status === 'broken') && breaks !== undefined ? [`  Breaks: ${breaks}`] : []),
+        ...((command.status === 'missing' || command.status === 'broken') && visibleBreaks !== undefined ? [`  Breaks: ${visibleBreaks}`] : []),
         ...((command.status === 'missing' || command.status === 'broken') && fix !== undefined ? [`  Fix: ${fix}`] : []),
       ].join('\n');
     }),
     ...(report.externalCommandsCatalogUnavailable ? [`External commands catalog unavailable: ${report.externalCommandsCatalogReason ?? 'catalog/external-commands.yaml is unavailable.'}`] : []),
     ...formatCapabilitySummary(capabilitySummary),
-    // 준비 상태는 «맨 끝» — 터미널에서 보이는 것은 끝이다. 09-25 베어 ubuntu:24.04: 224줄 중 준비 상태가
-    // 「못 하는 일」 40여 줄 위에 묻혀 스크롤 밖이었다.
-    ...formatReadiness(report.readiness),
   ].join('\n');
 }
 
+async function requestDoctorAdvice(report: DoctorReport, plan: ReturnType<typeof planDoctorFixes>, deps: DoctorCliDeps): Promise<DoctorAdvice & { provider: string; model: string; ms: number }> {
+  const started = Date.now();
+  const locale = detectLocale(process.env);
+  let provider = 'auto';
+  let model = '(none)';
+  const failure = (reason: string) => ({ ok: false, reason, summary: '', order: [], manual: [], dropped: 0, provider, model, ms: Date.now() - started });
+  const log = (event: 'requested' | 'advised' | 'failed', orderCount = 0, dropped = 0) =>
+    debug.log('doctor.advise', event, { provider, model, locale, ms: Date.now() - started, orderCount, dropped, applied: 0 });
+  log('requested');
+  try {
+    const config = deps.userConfig ?? (deps.getUserConfig ?? getUserConfig)();
+    const llm = await import('../llm.js');
+    const selected = (deps.resolveAdviceProvider ?? llm.decideProviderForConfig)(config);
+    provider = selected.provider.replace(/^auto:/, '');
+    model = selected.model;
+    if (selected.auth === 'none' || provider === 'auto' || !llm.PROVIDERS[provider]) {
+      log('failed');
+      const remedy = report.readiness?.items.find((item) => item.id === 'provider-decision')?.remedy ?? 'elanous login openai-codex';
+      return failure(`LLM 없음 — 구독이 있으면 \`elanous llm detect --probe --apply\`, 없으면 \`${remedy}\`(기기 코드) 뒤 다시 \`elanous doctor --advise\``);
+    }
+    const advice = await adviseDoctorFixes({
+      locale,
+      report: report.readiness ?? { items: [] },
+      plan: { ...plan, items: plan.items.filter((item) => item.status === 'fixable' && ADVISABLE_DOCTOR_FIX_IDS.has(item.id)) },
+      llm: (prompt) =>
+      deps.adviseLlm ? deps.adviseLlm(prompt, provider, model) : llm.streamLLM([
+        { role: 'system', content: 'Read-only diagnosis. Return JSON only. Never execute commands.' },
+        { role: 'user', content: prompt },
+      ], () => {}, { provider: llm.PROVIDERS[provider], model }),
+    });
+    log(advice.ok ? 'advised' : 'failed', advice.order.length, advice.dropped);
+    return { ...advice, provider, model, ms: Date.now() - started };
+  } catch {
+    log('failed');
+    return failure('LLM failed or timed out');
+  }
+}
+
+function formatDoctorAdvice(advice: DoctorAdvice): string {
+  if (!advice.ok) return advice.reason ?? 'LLM failed or timed out';
+  return [
+    `LLM 조언: ${advice.summary}`,
+    '순서  항목  수리 id  이유',
+    ...advice.order.map((entry, index) => `${index + 1}.  ${entry.readinessId}  ${entry.fixId ?? '사람 할 일'}  ${entry.why}`),
+    ...advice.manual.map((entry) => `사람 할 일: ${entry}`),
+    `버린 제안 ${advice.dropped}개`,
+  ].join('\n');
+}
+
+async function confirmDoctorAdvice(message: string, json: boolean): Promise<boolean> {
+  const prompt = createInterface({ input: process.stdin, output: json ? process.stderr : process.stdout });
+  try { return /^(y|yes)$/i.test((await prompt.question(message)).trim()); }
+  catch { return false; }
+  finally { prompt.close(); }
+}
+
 export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}): void {
   const out = deps.out ?? { log: (value: string) => console.log(value) };
   const err = deps.err ?? { error: (value: string) => console.error(value) };
@@ -1091,16 +1202,23 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
   program.command('doctor')
     .description('Reports whether credentials resolve and where each resolution comes from')
     .option('--json', 'structured output')
-    .option('--fix', 'show reversible repairs (read-only unless --yes)')
+    .option('--credentials', 'show per-credential details in human-readable output')
+    .option('--fix', 'show repairs; git installation asks on a TTY (other repairs require --yes)')
+    .option('--advise', 'ask the configured LLM to rank catalog repairs (read-only advice)')
     .option('--yes', 'apply planned doctor repairs (requires --fix)')
     .option('--sudo', 'also run the planned sudo install lines — only where `sudo -n true` works (requires --fix --yes)')
     .option('--restart', 'restart the nexus service when it runs a different version than this installed copy, then verify it (requires --fix --yes · interrupts bots, terminals and running turns)')
-    .action(async (opts: { json?: boolean; fix?: boolean; yes?: boolean; sudo?: boolean; restart?: boolean }) => {
+    .action(async (opts: { json?: boolean; credentials?: boolean; fix?: boolean; advise?: boolean; yes?: boolean; sudo?: boolean; restart?: boolean }) => {
       if (opts.yes && !opts.fix) {
         err.error('--yes requires --fix');
         setExitCode(1);
         return;
       }
+      if (opts.advise && (opts.sudo || opts.restart)) {
+        err.error('--advise does not run --sudo or --restart; use the deterministic --fix path for those actions');
+        setExitCode(1);
+        return;
+      }
       if (opts.sudo && !(opts.fix && opts.yes)) {
         err.error('--sudo requires --fix --yes');
         setExitCode(1);
@@ -1117,8 +1235,9 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
         setExitCode(1);
         return;
       }
-      if (!opts.fix) {
-        out.log(opts.json ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
+      if (!opts.fix && !opts.advise) {
+        out.log(opts.json ? JSON.stringify(report, null, 2) : formatDoctorReport(report, { credentials: opts.credentials }));
+        if (report.requiredMissing?.length) setExitCode(1);
         return;
       }
       const makeFixes = (source: DoctorReport): DoctorFixDeps => ({
@@ -1126,27 +1245,28 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
         home: deps.home,
         cacheDir: deps.cacheDir,
         readdir: deps.readdir,
-        readiness: deps.readiness ?? resolveReadinessDeps({
+        readiness: deps.readiness ?? { ...resolveReadinessDeps({
           env: deps.env ?? process.env,
           pathDelimiter: deps.pathDelimiter ?? delimiter,
           platform: deps.platform ?? process.platform,
           commandExists: deps.commandExists ?? ((name) => (deps.env ?? process.env).PATH?.split(deps.pathDelimiter ?? delimiter).some((dir) => existsSync(join(dir, name))) ?? false),
-          getConfig: deps.getUserConfig ?? getUserConfig,
-          listAuthProviders: deps.listAuthProviders ?? defaultListAuthProviders,
+          getConfig: () => deps.userConfig ?? (deps.getUserConfig ?? getUserConfig)(),
           codeRevision: deps.codeRevision ?? defaultCodeRevision,
-          fetchHealth: deps.fetchHealth ?? defaultFetchHealth,
+          fetchHealth: deps.fetchHealth ?? (() => defaultFetchHealth(deps.resolveDaemonEndpoint ?? resolveDaemonEndpoint)),
           readInstallPrefix: deps.readInstallPrefix ?? (() => defaultReadInstallPrefix(deps.repositoryRoot ?? repositoryRoot, deps.exists ?? existsSync)),
           ghAuthStatus: deps.ghAuthStatus ?? (() => null),
           // gh 판은 수리 계획에 쓰인다(낡은 gh → 정적 gh) — 🩸 09-25: 여기서 안 재서 계획은 보고서에만 뜨고 적용이 안 됐다.
           ghVersion: deps.ghVersion ?? (() => defaultGhVersion((name) => (deps.env ?? process.env).PATH?.split(deps.pathDelimiter ?? delimiter).some((dir) => existsSync(join(dir, name))) ?? false)),
           tmpdirSameFsAsBunCache: deps.tmpdirSameFsAsBunCache ?? (() => defaultTmpdirSameFsAsBunCache(deps.env ?? process.env)),
-          // 보고서와 같은 자로 — 로그인도 LLM 키도 없으면 계획에 «사람 한 줄»(로그인)이 실린다(🅢 #20263 ③).
-          ...(source.ok ? { llmKeyResolved: llmKeyResolvedFrom(source.credentials), nodePty: nodePtyStatus(source.externalCommands) } : {}),
+          ...(source.ok ? { nodePty: nodePtyStatus(source.externalCommands) } : {}),
           // L0 칸(substrate·docker·kubernetes·memory)은 «정보성·선택 기능»이라 수리 계획에 싣지 않는다 —
           // `--sudo` 가 `sudo systemctl start docker` 를 «설치 줄»로 치지 않게 하고, docker·kubectl 탐침(최대 수 초)을 두 번 돌리지 않는다.
           // 보고서(`runDoctor`)에는 그대로 나온다.
           probeHostEnvironment: () => null,
-        }),
+        }), usableLlm: (() => {
+          try { return deps.resolveLlm ? deps.resolveLlm() : resolveUsableLlm({ config: deps.userConfig ?? (deps.getUserConfig ?? getUserConfig)() }); }
+          catch { return null; }
+        })() },
         exists: deps.exists,
         readFile: deps.readFile,
         writeFile: deps.writeFile,
@@ -1157,36 +1277,101 @@ export function registerDoctorCommand(program: Command, deps: DoctorCliDeps = {}
         rename: deps.rename,
         remove: deps.remove,
         temporaryPath: deps.temporaryPath,
+        installStaticTool: deps.installStaticTool,
+        smokeCheck: deps.smokeCheck,
+        pythonSetup: deps.pythonSetup,
+        recheckPythonEnv: deps.recheckPythonEnv,
         // 키 캐시에서 다룰 이름 = doctor 가 보고하는 자격 이름(같은 `.env.example` · 소문자) — 다른 프로그램 캐시는 안 건드린다.
         keyNames: fixKeyNames(deps),
       });
       const fixes = makeFixes(report);
-      // registerDoctorCommand is the CLI caller: planning never writes; only --fix --yes reaches application.
+      // Planning never writes; existing repairs require --yes, while git alone can use affirmative TTY consent.
       const plan = planDoctorFixes(fixes);
+      const advice = opts.advise ? await requestDoctorAdvice(report, plan, deps) : undefined;
+      if (!opts.fix) {
+        out.log(opts.json
+          ? JSON.stringify({ ...report, advise: advice }, null, 2)
+          : [formatDoctorReport(report, { credentials: opts.credentials }), formatDoctorAdvice(advice!)].join('\n'));
+        if (report.requiredMissing?.length) setExitCode(1);
+        return;
+      }
+      const selected = advice?.ok
+        ? new Set<DoctorFixItem['id']>(advice.order.flatMap((entry): DoctorFixItem['id'][] => entry.fixId && entry.fixId !== 'git-install' && ADVISABLE_DOCTOR_FIX_IDS.has(entry.fixId) ? [entry.fixId] : []))
+        : undefined;
+      const selectedGit = advice?.ok ? advice.order.some((entry) => entry.fixId === 'git-install') : true;
+      const selectedCount = plan.items.filter((item) => item.status === 'fixable' && selected?.has(item.id)).length
+        + (selectedGit && advice?.ok && report.externalCommands.some((command) => command.name === 'git' && command.status === 'missing') ? 1 : 0);
+      const interactive = deps.adviceInteractive ?? (process.stdin.isTTY === true && (opts.json ? process.stderr.isTTY === true : process.stdout.isTTY === true));
+      if (advice?.ok && !opts.yes && interactive && selectedCount > 0) {
+        const preview = formatDoctorAdvice(advice);
+        if (opts.json) err.error(preview);
+        else out.log(preview);
+      }
+      const agreed = advice?.ok && !opts.yes && interactive && selectedCount > 0
+        ? await (deps.confirmAdvice ?? ((message) => confirmDoctorAdvice(message, opts.json === true)))(`위 ${selectedCount}개를 실행할까요? [y/N] `)
+        : false;
+      const applySelected = opts.yes || agreed;
+      const gitPlan = report.externalCommands.some((command) => command.name === 'git' && command.status === 'missing') ? gitPlanFor(deps) : undefined;
+      const installGit = () => applyGitInstall(gitPlan!, {
+        yes: advice?.ok ? applySelected : opts.yes,
+        interactive: advice?.ok ? false : deps.gitInteractive ?? (process.stdin.isTTY === true && (opts.json ? process.stderr.isTTY === true : process.stdout.isTTY === true)),
+        confirm: deps.confirmGitInstall,
+        run: deps.runGitInstallCommand,
+        platform: deps.platform ?? process.platform,
+        json: opts.json,
+      });
       // P5: sudo 설치 줄을 «먼저» 친다 — 빌드 도구가 서야 뒤의 node-pty 재빌드가 된다.
       const sudoResult = opts.sudo ? (deps.applySudoFixes ?? applySudoFixes)(plan.manual) : undefined;
       // sudo 로 뭔가 깔았으면 보고서·준비 상태를 «다시 잰다» — 빌드 도구가 선 뒤에야 node-pty 재빌드가 계획에 오른다.
       const afterSudo = sudoResult?.runs.some((entry) => entry.result === 'ran') ? makeFixes(runDoctor(deps)) : fixes;
-      const results = opts.yes ? applyDoctorFixes(afterSudo, true) : undefined;
+      let gitInstall: Awaited<ReturnType<typeof applyGitInstall>> | undefined;
+      let results: ReturnType<typeof applyDoctorFixes> | undefined;
+      if (advice?.ok && applySelected) {
+        // Invoke only known catalog operations, in the vetted order (including git).
+        const appliedItems: NonNullable<typeof results>['items'] = [];
+        for (const entry of advice.order) {
+          if (entry.fixId === 'git-install') {
+            if (gitPlan) gitInstall = await installGit();
+          } else if (entry.fixId && selected?.has(entry.fixId)) {
+            const single = applyDoctorFixes(afterSudo, true, new Set([entry.fixId]));
+            appliedItems.push(...single.items.filter((item) => item.id === entry.fixId));
+          }
+        }
+        const remaining = applyDoctorFixes(afterSudo, false, new Set<DoctorFixItem['id']>());
+        results = { items: [...appliedItems, ...remaining.items.filter((item) => !selected?.has(item.id))], exitCode: appliedItems.some((item) => item.result === 'failed') ? 1 : 0 };
+      } else {
+        gitInstall = gitPlan && selectedGit ? await installGit() : undefined;
+        results = applySelected ? applyDoctorFixes(afterSudo, true, selected) : undefined;
+      }
+      if (advice?.ok && (results || gitInstall?.ran)) debug.log('doctor.advise', 'applied', {
+        provider: advice.provider, model: advice.model, locale: detectLocale(process.env), ms: advice.ms, orderCount: advice.order.length,
+        dropped: advice.dropped, applied: (results?.items.filter((item) => item.result === 'fixed').length ?? 0) + (gitInstall?.ran && gitInstall.ok ? 1 : 0),
+      });
       // D5: 다른 수리가 다 끝난 «뒤» 재시작 — 서비스 파일을 고쳤으면 그 판으로 뜬다.
       const restartResult = opts.restart && afterSudo.readiness
         ? await (deps.applyServiceRestart ?? applyServiceRestart)({ readiness: afterSudo.readiness })
         : undefined;
       // PATH cannot change in this process; re-probe readiness rather than treating a saved block as PATH=ok.
-      const currentReport = results ? runDoctor(deps) : report;
-      if (opts.json) out.log(JSON.stringify({ report: currentReport, plan, manualCommands: manualCommandFixes(currentReport), ...(sudoResult ? { sudo: sudoResult } : {}), ...(results ? { results } : {}), ...(restartResult ? { restart: restartResult } : {}) }, null, 2));
+      const currentReport = results || gitInstall?.ran ? runDoctor(deps) : report;
+      if (gitInstall?.ran && gitInstall.ok && currentReport.requiredMissing?.includes('git')) {
+        gitInstall.detail = 'git init 성공 · 현재 doctor PATH 에서 git 을 찾지 못했습니다. 새 셸에서 다시 확인하세요.';
+      }
+      if (opts.json) out.log(JSON.stringify({ report: currentReport, plan, manualCommands: manualCommandFixes(currentReport), ...(gitPlan ? { gitPlan, gitInstall } : {}), ...(sudoResult ? { sudo: sudoResult } : {}), ...(results ? { results } : {}), ...(restartResult ? { restart: restartResult } : {}), ...(advice ? { advise: advice } : {}) }, null, 2));
       else out.log([
-        formatDoctorReport(currentReport),
-        '수정 계획:',
+        formatDoctorReport(currentReport, { credentials: opts.credentials }),
+        ...(advice ? [formatDoctorAdvice(advice)] : []),
+        'Fix plan:',
         ...plan.items.map((item) => `  ${item.id}: ${item.status} — ${item.path} — ${item.action}${item.reason ? ` — ${item.reason}` : ''}`),
         ...plan.manual.map((item) => `  ${item.id}: manual${item.remedy ? ` — ${item.remedy}` : ''}`),
         ...manualCommandFixes(currentReport).map((line) => `  ${line}`),
+        ...(gitInstall ? [`Git installation: ${gitInstall.detail}${gitPlan?.note ? ` — ${gitPlan.note}` : ''}`] : []),
         ...(sudoResult ? [sudoResult.sudoAvailable
-          ? `sudo 설치: ${sudoResult.runs.length ? sudoResult.runs.map((entry) => `${entry.result} — ${entry.command}${entry.detail ? ` — ${entry.detail}` : ''}`).join(' · ') : '칠 줄 없음'}`
-          : 'sudo 설치: 건너뜀 — 이 기계는 sudo 에 암호가 필요하다(sudo -n true 실패). 위 «manual» 줄을 직접 치세요.'] : []),
-        ...(results ? ['적용 결과:', ...results.items.map((item) => `  ${item.id}: ${item.result} — ${item.path}${item.reason ? ` — ${item.reason}` : ''}`)] : ['적용하려면 --fix --yes']),
-        ...(restartResult ? [`서비스 재시작: ${restartResult.result} — ${restartResult.reason}`] : []),
+          ? `Sudo installation: ${sudoResult.runs.length ? sudoResult.runs.map((entry) => `${entry.result} — ${entry.command}${entry.detail ? ` — ${entry.detail}` : ''}`).join(' · ') : '칠 줄 없음'}`
+          : 'Sudo installation: 건너뜀 — 이 기계는 sudo 에 암호가 필요하다(sudo -n true 실패). 위 «manual» 줄을 직접 치세요.'] : []),
+        ...(results ? ['Applied:', ...results.items.map((item) => `  ${item.id}: ${item.result} — ${item.path}${item.reason ? ` — ${item.reason}` : ''}`)] : ['적용하려면 --fix --yes']),
+        ...(restartResult ? [`Service restart: ${restartResult.result} — ${restartResult.reason}`] : []),
       ].join('\n'));
-      if (results) setExitCode(Math.max(results.exitCode, sudoResult?.exitCode ?? 0, restartResult?.result === 'failed' ? 1 : 0));
+      const exitCode = Math.max(results?.exitCode ?? 0, sudoResult?.exitCode ?? 0, restartResult?.result === 'failed' ? 1 : 0, currentReport.requiredMissing?.length ? 1 : 0, gitInstall?.ran && !gitInstall.ok ? 1 : 0);
+      if (results || exitCode) setExitCode(exitCode);
     });
 }