elanous 0.2.0 → 0.2.5

package/src/cli/doctor-distro.ts

@@ -58,6 +58,10 @@ export interface DistroRemedies {
   node?: string;
   /** node 가 준비된 뒤 codex CLI 설치 한 줄. */
   codex?: string;
+  /** jq 설치 한 줄(없는 계열에는 추측하지 않는다). */
+  jq?: string;
+  /** ffmpeg 설치 한 줄(기본 저장소에 없는 계열에는 두지 않는다). */
+  ffmpeg?: string;
   /** 계열별 주의 한 줄(없으면 생략). */
   note?: string;
 }
@@ -68,6 +72,8 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
     buildToolchain: 'xcode-select --install',
     pythonBuildDeps: 'brew install openssl readline sqlite3 xz zlib tcl-tk',
     gh: 'brew install gh',
+    jq: 'brew install jq',
+    ffmpeg: 'brew install ffmpeg',
     rg: 'brew install ripgrep',
     node: 'brew install node',
     codex: 'npm install -g @openai/codex',
@@ -77,8 +83,10 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
     pythonBuildDeps: 'sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl git libncurses-dev xz-utils tk-dev libffi-dev liblzma-dev',
     // 🩸 09-24 빈 GCP Ubuntu 24.04 실측: 목록 갱신 없이 `apt-get install -y gh` → «Unable to locate package gh».
     gh: 'sudo apt-get update && sudo apt-get install -y gh',
+    jq: 'sudo apt-get update && sudo apt-get install -y jq',
+    ffmpeg: 'sudo apt-get update && sudo apt-get install -y ffmpeg',
     rg: 'sudo apt-get update && sudo apt-get install -y ripgrep',
-    node: 'sudo apt-get update && sudo apt-get install -y nodejs npm',
+    node: 'Install Node.js 20+ using the official distribution instructions at https://nodejs.org/en/download',
     codex: 'sudo npm install -g @openai/codex',
     pythonVenv: 'sudo apt-get install -y python3-venv',
     pythonBase: 'sudo apt-get update && sudo apt-get install -y python3 python3-venv',
@@ -89,6 +97,7 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
     pythonBuildDeps: 'sudo dnf install -y gcc make patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel',
     // 🩸 2026-09-25 fedora:latest 컨테이너: dnf5 는 `config-manager --add-repo` 를 모른다. gh 는 Fedora 공식 저장소에 있다.
     gh: 'sudo dnf install -y gh',
+    jq: 'sudo dnf install -y jq',
     rg: 'sudo dnf install -y ripgrep',
     node: 'sudo dnf install -y nodejs npm',
     codex: 'sudo npm install -g @openai/codex',
@@ -99,6 +108,7 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
     buildToolchain: 'sudo dnf install -y gcc-c++ make',
     pythonBuildDeps: 'sudo dnf install -y gcc make patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel',
     gh: "sudo dnf install -y 'dnf-command(config-manager)' && sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && sudo dnf install -y gh",
+    jq: 'sudo dnf install -y jq',
     node: 'sudo dnf install -y nodejs npm',
     codex: 'sudo npm install -g @openai/codex',
     note: 'ripgrep is not in the AL2023 base repos — install it manually; the system python3 is 3.9 (older than the declared 3.12)',
@@ -108,6 +118,7 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
     pythonBuildDeps: 'sudo yum install -y gcc make patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl11-devel tk-devel libffi-devel xz-devel',
     // 🩸 2026-09-25 amazonlinux:2 컨테이너: yum-config-manager 는 yum-utils 에 있고 기본 이미지엔 없다.
     gh: 'sudo yum install -y yum-utils && sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo && sudo yum install -y gh',
+    jq: 'sudo yum install -y jq',
     // ⛔ rg·node 줄을 두지 않는다(🅢 수확 2026-09-24): AL2 기본 저장소에 ripgrep·nodejs 가 없고, 제3자 저장소(COPR 등)를
     //    `--sudo` 가 자동으로 붙이는 것은 위험하며 aarch64 에서는 실행도 안 된다(리뷰 must-fix). 이름만 대고 사람이 고른다.
     codex: 'sudo npm install -g @openai/codex',
@@ -119,3 +130,8 @@ export const DISTRO_REMEDIES: Readonly<Record<Exclude<DistroFamily, 'unknown'>,
 export function remediesFor(family: DistroFamily): DistroRemedies | undefined {
   return family === 'unknown' ? undefined : DISTRO_REMEDIES[family];
 }
+
+/** 표에 명시된 도구 설치 줄만 돌려준다 — 모르는 계열·빈 칸은 undefined. */
+export function toolInstallLine(tool: 'gh' | 'rg' | 'node' | 'codex' | 'jq' | 'ffmpeg', family: DistroFamily): string | undefined {
+  return remediesFor(family)?.[tool];
+}

package/src/cli/doctor-fix.ts

@@ -1,19 +1,90 @@
 import { nativeBuildEnv, nativeBuildShimDir } from '../native/native-build-env.js';
+import { debug } from '../debug/log.js';
+import type { GitInstallPlan } from './git-install-plan.js';
+import { createInterface } from 'node:readline/promises';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { fixPrivateFiles, scanPrivateFiles } from './doctor-private-files.js';
 import { checkPythonEnv, runPythonSetup } from './python-cli.js';
-import { remediesFor } from './doctor-distro.js';
+import { remediesFor, toolInstallLine } from './doctor-distro.js';
 import { installManagedPython, installStaticTool, linuxArch, staticToolBinDir, STATIC_TOOLS, type StaticToolName } from './doctor-static-tools.js';
 import { declaredPythonVersion, PYTHON_MIN_SUPPORTED } from '../python/resolve-python.js';
 import { randomUUID } from 'node:crypto';
-import { appendFileSync, chmodSync, closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { appendFileSync, chmodSync, closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve, win32 } from 'node:path';
 import { checkReadiness, ghVersionAtLeast, serviceSecretEntries, SERVICE_VERSION_FOLDER, type ReadinessDeps, type ReadinessItem } from './doctor-readiness.js';
 
+export interface GitInstallResult {
+  ran: boolean;
+  ok: boolean;
+  detail: string;
+}
+
+/** Installation is never attempted without an explicit yes or an affirmative TTY answer. */
+export async function applyGitInstall(plan: GitInstallPlan, deps: {
+  yes?: boolean;
+  interactive?: boolean;
+  confirm?: (display: string) => Promise<boolean>;
+  run?: (command: string, args: readonly string[]) => { status: number | null };
+  platform?: NodeJS.Platform;
+  json?: boolean;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  waitForGitMs?: number;
+  pollMs?: number;
+} = {}): Promise<GitInstallResult> {
+  const run = deps.run ?? ((command: string, args: readonly string[]) => {
+    const result = spawnSync(command, [...args], { stdio: ['inherit', deps.json ? process.stderr : process.stdout, process.stderr], timeout: 1_800_000 });
+    return { status: result.status };
+  });
+  const confirm = deps.confirm ?? (async (display: string) => {
+    const prompt = createInterface({ input: process.stdin, output: deps.json ? process.stderr : process.stdout });
+    try { return /^(y|yes)$/i.test((await prompt.question(`${display} 실행할까요? [y/N] `)).trim()); }
+    catch { return false; }
+    finally { prompt.close(); }
+  });
+  let agreed = deps.yes === true;
+  if (!agreed && deps.interactive === true && plan.command !== null) {
+    try { agreed = await confirm(plan.display); } catch { agreed = false; }
+  }
+  let ran = false;
+  let ok = false;
+  let detail = plan.command === null ? plan.display : '설치하지 않음 — --fix --yes 또는 대화형 동의가 필요합니다.';
+  if (agreed && plan.command) {
+    ran = true;
+    try {
+      let preOk = true;
+      for (const pre of plan.preCommands ?? []) {
+        if (run(pre[0]!, pre.slice(1)).status !== 0) { preOk = false; break; }
+      }
+      const installed = preOk ? run(plan.command[0]!, plan.command.slice(1)) : { status: 1 };
+      if (installed.status === 0) {
+        ok = smokeCheck('git', 'git', run);
+        // xcode-select returns as soon as Apple's installer window opens — wait for git to appear.
+        if (!ok && plan.waitForGit) {
+          const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+          const deadline = (deps.now ?? Date.now)() + (deps.waitForGitMs ?? 15 * 60_000);
+          while (!ok && (deps.now ?? Date.now)() < deadline) {
+            await sleep(deps.pollMs ?? 10_000);
+            ok = smokeCheck('git', 'git', run);
+          }
+        }
+      }
+      detail = ok ? 'git init 재확인 성공' : 'git 설치 또는 git init 재확인 실패';
+    } catch {
+      detail = 'git 설치 또는 git init 재확인 실패';
+    }
+  }
+  debug.log('doctor.fix', 'git-install', { platform: deps.platform ?? process.platform, command: plan.command, ran, ok });
+  return { ran, ok, detail };
+}
+
 export interface DoctorFixDeps {
   env?: NodeJS.ProcessEnv;
   home?: string;
   cacheDir?: string;
+  configDir?: string;
   readiness?: ReadinessDeps;
   readdir?: (path: string) => string[];
   exists?: (path: string) => boolean;
@@ -48,12 +119,14 @@ export interface DoctorFixDeps {
   arch?: string;
   /** 정적 도구 설치(시험 주입 · 기본 = doctor-static-tools). */
   installStaticTool?: (name: StaticToolName, dest: string) => { ok: boolean; detail: string };
+  /** 설치 뒤 실제 도구 동작 확인(시험 주입). */
+  smokeCheck?: (name: StaticToolName, dest: string) => boolean;
   /** 관리형 파이썬 설치(시험 주입). */
   installManagedPython?: (minor: string) => { python: string | null; detail: string };
 }
 
 export interface DoctorFixItem {
-  id: 'install-path' | 'key-cache-permissions' | 'bun-tmpdir' | 'service-file' | 'service-secrets' | 'node-pty-rebuild' | 'python-env' | 'static-tools' | 'python-managed';
+  id: 'private-files' | 'install-path' | 'key-cache-permissions' | 'bun-tmpdir' | 'service-file' | 'service-secrets' | 'node-pty-rebuild' | 'python-env' | 'static-tools' | 'python-managed';
   path: string;
   action: string;
   status: 'fixable' | 'skipped' | 'failed';
@@ -66,7 +139,7 @@ export interface DoctorFixResult {
   exitCode: number;
 }
 
-type IO = Required<Omit<DoctorFixDeps, 'readiness' | 'keyNames' | 'realpath' | 'runCommand' | 'verifyNodePty' | 'pythonSetup' | 'recheckPythonEnv' | 'shimDir' | 'removeTree' | 'arch' | 'installStaticTool' | 'installManagedPython'>> & { readiness: ReadinessDeps; keyNames: readonly string[] | undefined };
+type IO = Required<Omit<DoctorFixDeps, 'configDir' | 'readiness' | 'keyNames' | 'realpath' | 'runCommand' | 'verifyNodePty' | 'pythonSetup' | 'recheckPythonEnv' | 'shimDir' | 'removeTree' | 'arch' | 'installStaticTool' | 'smokeCheck' | 'installManagedPython'>> & { readiness: ReadinessDeps; keyNames: readonly string[] | undefined };
 const cachePath = Symbol('cachePath');
 type InternalFixItem = DoctorFixItem & { [cachePath]?: string };
 const START = '# >>> elanous installer PATH >>>';
@@ -391,11 +464,11 @@ function pythonEnvItem(deps: DoctorFixDeps): InternalFixItem | undefined {
  *  📏 2026-09-25 amazonlinux:2·2023 컨테이너에서 실측(`doctor-static-tools.ts` 머리말). sudo 불필요. */
 export function staticToolsNeeded(readiness: ReadinessDeps): StaticToolName[] {
   if (readiness.platform !== 'linux') return [];
-  const remedies = remediesFor(readiness.distro ?? 'unknown');
+  const family = readiness.distro ?? 'unknown';
   const tools: StaticToolName[] = [];
-  if (readiness.rgOnPath === false && !remedies?.rg) tools.push('rg');
+  if (readiness.rgOnPath === false && !toolInstallLine('rg', family)) tools.push('rg');
   // node 를 깔 줄이 있으면 codex 는 npm 길(sudo)로 — 없을 때만 정적 바이너리(node 불필요).
-  if (readiness.codexOnPath === false && readiness.nodeOnPath === false && !remedies?.node) tools.push('codex');
+  if (readiness.codexOnPath === false && readiness.nodeOnPath === false && !toolInstallLine('node', family)) tools.push('codex');
   // codex 바이너리는 있는데 짝이 없다 — 한 벌로 다시 깐다(elanous bin 이 PATH 앞이라 그쪽이 쓰인다).
   else if (readiness.codexOnPath === true && readiness.codexCodeModeHost === false) tools.push('codex');
   // gh 가 없거나 낡았다(배포판 gh 가 GH_MIN_VERSION 미만) — 고정 판 정적 gh(elanous bin 이 PATH 앞이라 그쪽이 쓰인다).
@@ -443,8 +516,17 @@ function nodePtyItem(deps: DoctorFixDeps): InternalFixItem | undefined {
   return { id: 'node-pty-rebuild', path: plan.versionDir, action: `${envText}bun add ${plan.spec} (in ${plan.versionDir}) — then require('node-pty')`, status: 'fixable' };
 }
 
+function privateFilesItem(deps: DoctorFixDeps, fs: IO): DoctorFixItem | undefined {
+  const configDir = deps.configDir ?? (deps.home ? join(deps.home, '.elanous') : getElanousConfigDir());
+  const scan = scanPrivateFiles(configDir, fs);
+  if (scan.dirMode === null || (scan.dirMode === 0o700 && scan.loose.length === 0)) return undefined;
+  return { id: 'private-files', path: configDir, action: 'chmod directory 700 and restrict private files', status: 'fixable',
+    reason: `directory ${scan.dirMode.toString(8)} · files ${scan.loose.length}` };
+}
+
 export function planDoctorFixes(deps: DoctorFixDeps = {}): DoctorFixPlan {
   const fs = io(deps);
+  const privateFiles = privateFilesItem(deps, fs);
   const path = pathItem(fs);
   const tmpdir = tmpdirItem(fs);
   const service = serviceItem(fs);
@@ -454,7 +536,7 @@ export function planDoctorFixes(deps: DoctorFixDeps = {}): DoctorFixPlan {
   const staticTools = staticToolsItem(deps, fs);
   const pythonManaged = pythonManagedItem(deps, fs);
   return {
-    items: [...(path ? [path] : []), ...(tmpdir ? [tmpdir] : []), ...(secrets ? [secrets] : []), ...(service ? [service] : []), ...(nodePty ? [nodePty] : []), ...(staticTools ? [staticTools] : []), ...(pythonManaged ? [pythonManaged] : []), ...(python ? [python] : []), ...cacheItems(fs)],
+    items: [...(path ? [path] : []), ...(tmpdir ? [tmpdir] : []), ...(secrets ? [secrets] : []), ...(service ? [service] : []), ...(nodePty ? [nodePty] : []), ...(staticTools ? [staticTools] : []), ...(pythonManaged ? [pythonManaged] : []), ...(python ? [python] : []), ...cacheItems(fs), ...(privateFiles ? [privateFiles] : [])],
     manual: checkReadiness(fs.readiness).items.filter((item) => item.status === 'manual'),
   };
 }
@@ -464,21 +546,64 @@ function defaultVerifyNodePty(packageDir: string): boolean {
   return r.status === 0;
 }
 
-export function applyDoctorFixes(deps: DoctorFixDeps = {}, yes = false): DoctorFixResult {
+export function smokeCheck(name: StaticToolName | 'git', dest: string, run?: (command: string, args: readonly string[]) => { status: number | null }): boolean {
+  if (name === 'uv') return true;
+  if (name === 'codex-code-mode-host') {
+    if (run) return run(dest, ['--help']).status === 0;
+    const hello = Buffer.from(JSON.stringify({ type: 'connection/hello', supportedVersions: [1], requiredCapabilities: [], optionalCapabilities: [] }));
+    const frame = Buffer.alloc(4 + hello.length);
+    frame.writeUInt32LE(hello.length, 0);
+    hello.copy(frame, 4);
+    const reply = spawnSync(dest, [], { input: frame, timeout: 15_000, maxBuffer: 1024 * 1024 });
+    if (reply.status !== 0 || reply.stdout.length < 5) return false;
+    const length = reply.stdout.readUInt32LE(0);
+    if (length !== reply.stdout.length - 4) return false;
+    try {
+      const ready = JSON.parse(reply.stdout.subarray(4).toString('utf8')) as { type?: string; selectedVersion?: number };
+      return ready.type === 'connection/ready' && ready.selectedVersion === 1;
+    } catch { return false; }
+  }
+  const work = mkdtempSync(join(tmpdir(), name === 'git' ? 'elanous-doctor-git-' : 'elanous-doctor-tool-'));
+  try {
+    const args = name === 'git' ? ['init', work] : name === 'rg' ? ['doctor smoke', 'smoke.txt'] : name === 'gh' ? ['help'] : ['--help'];
+    if (name === 'rg') writeFileSync(join(work, 'smoke.txt'), 'doctor smoke\n');
+    return (run ? run(dest, args) : spawnSync(dest, args, { cwd: work, stdio: 'ignore', timeout: 15_000 })).status === 0;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+export function applyDoctorFixes(deps: DoctorFixDeps = {}, yes = false, only?: ReadonlySet<DoctorFixItem['id']>): DoctorFixResult {
   const fs = io(deps);
   const plan = planDoctorFixes(deps);
   if (!yes) return {
-    items: plan.items.map((item) => ({ ...item, result: item.status === 'failed' ? 'failed' : 'skipped', reason: item.reason ?? 'requires --yes' })),
-    exitCode: plan.items.some((item) => item.status === 'failed') ? 1 : 0,
+    items: plan.items.map((item) => only && !only.has(item.id)
+      ? { ...item, result: 'skipped' as const, reason: 'not selected' }
+      : { ...item, result: item.status === 'failed' ? 'failed' as const : 'skipped' as const, reason: item.reason ?? 'requires --yes' }),
+    exitCode: plan.items.some((item) => item.status === 'failed' && (!only || only.has(item.id))) ? 1 : 0,
   };
   const items: DoctorFixResult['items'] = [];
   for (const item of plan.items) {
+    if (only && !only.has(item.id)) {
+      items.push({ ...item, result: 'skipped', reason: 'not selected' });
+      continue;
+    }
     if (item.status !== 'fixable') {
       items.push({ ...item, result: item.status === 'failed' ? 'failed' : 'skipped' });
       continue;
     }
     try {
-      if (item.id === 'install-path') {
+      if (item.id === 'private-files') {
+        const scan = scanPrivateFiles(item.path, fs);
+        if (scan.dirMode === null || (scan.dirMode === 0o700 && !scan.loose.length)) {
+          items.push({ ...item, result: 'skipped', reason: 'permissions already private' });
+          continue;
+        }
+        fixPrivateFiles(scan, fs);
+        const after = scanPrivateFiles(item.path, fs);
+        const repaired = after.dirMode === 0o700 && after.loose.length === 0;
+        items.push({ ...item, result: repaired ? 'fixed' : 'failed', reason: repaired ? 'permissions restricted' : 'permissions remain loose' });
+      } else if (item.id === 'install-path') {
         // Reinspect immediately before writing; a competing installer may have changed it.
         const current = pathItem(fs);
         if (current?.status !== 'fixable') {
@@ -535,11 +660,14 @@ export function applyDoctorFixes(deps: DoctorFixDeps = {}, yes = false): DoctorF
       } else if (item.id === 'static-tools') {
         const arch = linuxArch(deps.arch)!;
         // codex 는 짝(`codex-code-mode-host`)과 «한 벌»이다 — 없으면 셸 도구가 못 뜬다(2026-09-25 L2 실측).
-        const outcomes = staticToolsNeeded(deps.readiness ?? {})
+        const tools = staticToolsNeeded(deps.readiness ?? {});
+        const outcomes = tools
           .flatMap((tool): StaticToolName[] => (tool === 'codex' ? ['codex', 'codex-code-mode-host'] : [tool]))
           .map((tool) => (deps.installStaticTool ?? ((name, to) => installStaticTool(name, arch, to)))(tool, join(item.path, tool)));
-        const ok = outcomes.length > 0 && outcomes.every((o) => o.ok);
-        items.push({ ...item, result: ok ? 'fixed' : 'failed', reason: outcomes.map((o) => o.detail).join(' · ') || 'nothing to install' });
+        const installed = outcomes.length > 0 && outcomes.every((o) => o.ok);
+        const verified = installed && tools.every((tool) => (deps.smokeCheck ?? smokeCheck)(tool, join(item.path, tool)) &&
+          (tool !== 'codex' || (deps.smokeCheck ?? smokeCheck)('codex-code-mode-host', join(item.path, 'codex-code-mode-host'))));
+        items.push({ ...item, result: verified ? 'fixed' : 'failed', reason: installed && !verified ? 'installed, but smoke check failed' : outcomes.map((o) => o.detail).join(' · ') || 'nothing to install' });
       } else if (item.id === 'python-managed') {
         const got = (deps.installManagedPython ?? ((minor) => installManagedPython(minor, { env: fs.env, home: fs.home })))(managedPythonMinor());
         if (!got.python) { items.push({ ...item, result: 'failed', reason: got.detail }); continue; }
@@ -585,7 +713,7 @@ export function applyDoctorFixes(deps: DoctorFixDeps = {}, yes = false): DoctorF
         items.push({ ...item, result: repaired ? 'fixed' : 'failed', reason: repaired ? 'permissions are 600' : 'permissions remain different from 600' });
       }
     } catch {
-      items.push({ ...item, result: 'failed', reason: item.id === 'key-cache-permissions' ? 'could not chmod or recheck cache file' : item.id === 'service-secrets' ? 'could not migrate cache or back up, write or recheck service file' : 'could not back up, write or recheck startup file' });
+      items.push({ ...item, result: 'failed', reason: item.id === 'key-cache-permissions' ? 'could not chmod or recheck cache file' : item.id === 'service-secrets' ? 'could not migrate cache or back up, write or recheck service file' : item.id === 'private-files' ? 'could not chmod or recheck private files' : 'could not back up, write or recheck startup file' });
     }
   }
   return { items, exitCode: items.some((item) => item.result === 'failed') ? 1 : 0 };

package/src/cli/doctor-llm-assist.ts

@@ -0,0 +1,71 @@
+import { redactSecretText } from '../debug/log.js';
+import type { ReadinessReport } from './doctor-readiness.js';
+import type { DoctorFixItem, DoctorFixPlan } from './doctor-fix.js';
+
+// Only tool/runtime installs are model-selectable; startup files, service units, installed code and credential stores are not.
+export const ADVISABLE_DOCTOR_FIX_IDS: ReadonlySet<DoctorFixItem['id']> = new Set([
+  'python-env', 'static-tools', 'python-managed',
+]);
+
+export interface DoctorAdvice {
+  ok: boolean;
+  reason?: string;
+  summary: string;
+  order: Array<{ readinessId: string; fixId?: DoctorFixItem['id'] | 'git-install'; why: string }>;
+  manual: string[];
+  dropped: number;
+}
+
+/** The model ranks known repairs; it never supplies a command or an executable action. */
+export async function adviseDoctorFixes({ report, plan, llm, locale = 'en', timeoutMs = 60_000 }: {
+  report: ReadinessReport;
+  plan: DoctorFixPlan;
+  llm?: (prompt: string) => Promise<string>;
+  locale?: 'en' | 'ko' | 'ja' | 'zh';
+  timeoutMs?: number;
+}): Promise<DoctorAdvice> {
+  const empty = (reason: string): DoctorAdvice => ({ ok: false, reason, summary: '', order: [], manual: [], dropped: 0 });
+  if (!llm) return empty('LLM unavailable');
+  const language = { en: 'English', ko: 'Korean', ja: 'Japanese', zh: 'Chinese' }[locale];
+  const prompt = JSON.stringify({
+    instruction: `Read-only diagnosis. Return only JSON: {"summary":"...","order":[{"readinessId":"...","fixId":"optional catalog id or git-install","why":"..."}],"manual":["..."]}. Choose fixId only from the supplied repair plan or git-install. Never return shell commands. Do not execute anything. Write summary, why and manual in ${language}. Keep JSON keys and repair ids in English.`,
+    readiness: report.items.map(({ id, status, evidence, remedy }) => ({ id: redactSecretText(id), status, evidence: redactSecretText(evidence), ...(remedy === undefined ? {} : { remedy: redactSecretText(remedy) }) })),
+    plan: plan.items.map(({ id, action, status }) => ({ id, action: redactSecretText(action), status })),
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const raw = await Promise.race([
+      Promise.resolve().then(() => llm(prompt)),
+      new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), timeoutMs); }),
+    ]);
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch { return empty('invalid JSON'); }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return empty('invalid JSON shape');
+    const value = parsed as Record<string, unknown>;
+    if (typeof value.summary !== 'string' || !Array.isArray(value.order) || !Array.isArray(value.manual) || !value.manual.every((line: unknown) => typeof line === 'string')) return empty('invalid JSON shape');
+    const ids: ReadonlySet<string> = new Set(plan.items.filter((item) => item.status === 'fixable' && ADVISABLE_DOCTOR_FIX_IDS.has(item.id)).map((item) => item.id));
+    const readinessIds = new Set(report.items.map((item) => item.id));
+    const seenReadiness = new Set<string>();
+    const seenFix = new Set<string>();
+    let dropped = 0;
+    const order: DoctorAdvice['order'] = [];
+    for (const candidate of value.order as unknown[]) {
+      if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) { dropped++; continue; }
+      const { readinessId, fixId, why } = candidate as Record<string, unknown>;
+      if (typeof readinessId !== 'string' || !readinessIds.has(readinessId) || typeof why !== 'string'
+        || (fixId !== undefined && (typeof fixId !== 'string' || (fixId !== 'git-install' && !ids.has(fixId))))
+        || seenReadiness.has(readinessId) || (typeof fixId === 'string' && seenFix.has(fixId))) {
+        dropped++;
+        continue;
+      }
+      seenReadiness.add(readinessId);
+      if (typeof fixId === 'string') seenFix.add(fixId);
+      order.push({ readinessId, ...(fixId === undefined ? {} : { fixId: fixId as DoctorFixItem['id'] | 'git-install' }), why: redactSecretText(why) });
+    }
+    return { ok: true, summary: redactSecretText(value.summary), order, manual: value.manual.map((line: string) => redactSecretText(line)), dropped };
+  } catch {
+    return empty('LLM failed or timed out');
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/cli/doctor-private-files.ts

@@ -0,0 +1,66 @@
+import { chmodSync, existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export interface PrivateFilesDeps {
+  exists?: (path: string) => boolean;
+  readdir?: (path: string) => string[];
+  lstat?: (path: string) => { mode: number; isDirectory?: () => boolean; isFile: () => boolean; isSymbolicLink: () => boolean };
+  chmod?: (path: string, mode: number) => void;
+}
+
+export interface PrivateFilesScan {
+  /** Directory to repair, including when only its own mode is loose. */
+  configDir: string;
+  /** null means the directory does not exist. */
+  dirMode: number | null;
+  loose: { path: string; mode: number }[];
+}
+
+export interface PrivateFilesFix {
+  dir: { path: string; before: number; after: number } | null;
+  files: { path: string; before: number; after: number }[];
+}
+
+const PRIVATE_NAME = /^(?:(?:config|secrets|auth|llm-fallback)\.json.*|.*\.bak.*)$/;
+
+/** Inspect only immediate regular files, by name and lstat mode; never read their contents or follow links. */
+export function scanPrivateFiles(configDir: string, deps: PrivateFilesDeps = {}): PrivateFilesScan {
+  const exists = deps.exists ?? existsSync;
+  if (!exists(configDir)) return { configDir, dirMode: null, loose: [] };
+  const lstat = deps.lstat ?? lstatSync;
+  const directory = lstat(configDir);
+  if (directory.isSymbolicLink() || directory.isFile() || (directory.isDirectory && !directory.isDirectory())) throw new Error('config directory is not a directory');
+  const loose: PrivateFilesScan['loose'] = [];
+  for (const name of (deps.readdir ?? readdirSync)(configDir).sort()) {
+    if (name === '.' || name === '..' || name.includes('/') || name.includes('\\') || !PRIVATE_NAME.test(name)) continue;
+    const path = join(configDir, name);
+    const stat = lstat(path);
+    if (stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o044)) loose.push({ path, mode: stat.mode & 0o7777 });
+  }
+  return { configDir, dirMode: directory.mode & 0o7777, loose };
+}
+
+/** Reinspect just before chmod so stale scan modes cannot restore old owner bits. */
+export function fixPrivateFiles(scan: PrivateFilesScan, deps: PrivateFilesDeps = {}): PrivateFilesFix {
+  const lstat = deps.lstat ?? lstatSync;
+  const chmod = deps.chmod ?? chmodSync;
+  const dirStat = lstat(scan.configDir);
+  if (dirStat.isSymbolicLink() || dirStat.isFile() || (dirStat.isDirectory && !dirStat.isDirectory())) throw new Error('config directory is not a directory');
+  const dirBefore = dirStat.mode & 0o7777;
+  const dir = dirBefore === 0o700 ? null : { path: scan.configDir, before: dirBefore, after: 0o700 };
+  if (dir) chmod(dir.path, dir.after);
+  const files: PrivateFilesFix['files'] = [];
+  for (const entry of scan.loose) {
+    const stat = lstat(entry.path);
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    const before = stat.mode & 0o7777;
+    const after = before & ~0o077;
+    if (after === before) continue;
+    chmod(entry.path, after);
+    files.push({ path: entry.path, before, after });
+  }
+  const result = { dir, files };
+  debug.log('doctor.private-files', 'fixed', result);
+  return result;
+}

package/src/cli/doctor-readiness.ts

@@ -1,4 +1,5 @@
 import { remediesFor, type DistroFamily } from './doctor-distro.js';
+import type { UsableLlm } from '../llm/usable-llm.js';
 import { providerSecretNames } from '../nexus/install/launchd.js';
 import { win32 } from 'node:path';
 /**
@@ -42,13 +43,8 @@ export interface ReadinessDeps {
    * must pass `null` rather than omit it).
    */
   provider?: string | null;
-  /**
-   * Codex subscription login is present. `null` means not measured.
-   * The token itself is never passed in.
-   */
-  codexLogin?: boolean | null;
-  /** LLM 을 부를 자격이 «하나라도» 있나(어떤 로그인이든 · LLM 키가 풀렸든). 없으면(undefined/null) 못 쟀다. */
-  llmCredentialAvailable?: boolean | null;
+  /** Selected runtime route, already resolved with the runtime auto selector. null = unmeasured. */
+  usableLlm?: UsableLlm | null;
   /** `gh` is on PATH. `null` means not measured. */
   ghOnPath?: boolean | null;
   /** `gh --version` 의 판 · null/undefined = 못 쟀다. */
@@ -210,23 +206,19 @@ function providerDecision(deps: ReadinessDeps): ReadinessItem {
     return item('provider-decision', 'unknown', 'llm.provider was not measured');
   }
   const provider = deps.provider.trim() || 'auto';
-  if (provider !== 'auto') {
-    // 아는 provider 이름만 보여 준다 — 설정 칸에 자격 같은 값이 들어와 있어도 보고에 싣지 않는다.
-    const shown = KNOWN_PROVIDERS.has(provider) ? provider : '(set · value not shown)';
-    return item('provider-decision', 'ok', `llm.provider=${shown}`);
-  }
-  if (deps.codexLogin === undefined || deps.codexLogin === null) {
-    return item('provider-decision', 'unknown', 'llm.provider=auto but codex login was not measured');
-  }
-  if (deps.codexLogin === true) {
-    // 2026-09-24 결정(`#20142`) — auto 는 codex 구독을 먼저 쓰고 계정 회전·llm.fallbackChain 이 뒤를 잇는다.
-    return item('provider-decision', 'ok', 'llm.provider=auto uses the codex login first; account rotation and llm.fallbackChain apply');
-  }
-  // 🩸 2026-09-24 빈 VM(🅢 #20263): 로그인도 키도 없는데 여기서 `ok` 가 나왔다(거짓 초록) — auto 가 고를 것이 없다.
-  if (deps.llmCredentialAvailable === false) {
-    return item('provider-decision', 'manual', 'llm.provider=auto but no LLM login or key was found — LLM commands will fail', 'elanous login openai-codex');
+  const shown = KNOWN_PROVIDERS.has(provider) ? provider : '(set · value not shown)';
+  if (deps.usableLlm == null) return item('provider-decision', 'unknown', `llm.provider=${shown} route was not measured`);
+  const { usable, provider: selected, via, why } = deps.usableLlm;
+  if (!usable) {
+    const reason = why === 'no usable LLM route selected' ? why : 'route unavailable';
+    const remedy = provider === 'auto' || provider === 'openai-codex' ? 'elanous login openai-codex'
+      : provider === 'openai' ? 'Set OPENAI_API_KEY or llm.apiKey for openai'
+      : provider === 'local' ? 'Set llm.baseUrl or LOCAL_LLM_URL for local'
+      : KNOWN_PROVIDERS.has(provider) ? `Configure credentials for llm.provider=${provider}` : undefined;
+    return item('provider-decision', 'manual', `llm.provider=${shown} selected no usable LLM (via none) — ${reason}`, remedy);
   }
-  return item('provider-decision', 'ok', 'llm.provider=auto and no codex login');
+  const selectedName = selected && KNOWN_PROVIDERS.has(selected) ? selected : 'selected provider';
+  return item('provider-decision', 'ok', `llm.provider=${shown} → ${via} ${selectedName}`);
 }
 
 /** Debian 계열 apt 의 gh 는 GH_MIN_VERSION 미만이다(📏 09-25: Debian 12 = 2.23 · Ubuntu 24.04 = 2.45) — apt 로 깔면 곧바로
@@ -291,16 +283,17 @@ function harnessTools(deps: ReadinessDeps): ReadinessItem {
   const remedies = remediesFor(deps.distro ?? 'unknown');
   const commands = [
     rgOnPath === false ? remedies?.rg : undefined,
-    nodeMissing ? remedies?.node : undefined,
-    // node 를 깔 줄이 없으면 codex(npm) 줄도 내지 않는다 — 🩸 2026-09-25 amazonlinux:2: `sudo: npm: command not found`.
-    codexOnPath === false && nodeOnPath != null && (!nodeMissing || remedies?.node) ? remedies?.codex : undefined,
+    nodeMissing && deps.distro !== 'debian' ? remedies?.node : undefined,
+    // On Debian, Node installation is an instruction, not a shell command: npm cannot run until Node is installed.
+    codexOnPath === false && nodeOnPath != null && (!nodeMissing || (deps.distro !== 'debian' && remedies?.node)) ? remedies?.codex : undefined,
   ].filter((command): command is string => command !== undefined);
+  const nodeInstruction = nodeMissing && deps.distro === 'debian' ? remedies?.node : undefined;
   const nodeEvidence = nodeMissing ? ' (node missing)' : codexOnPath === false && nodeOnPath == null ? ' (node not measured)' : '';
   // 계열에 설치 줄이 없는 도구는 «추측하지 않고» 이름을 댄다(예: Amazon Linux 2 의 rg·node).
   const noLine = [rgOnPath === false && !remedies?.rg ? 'rg' : '', nodeMissing && !remedies?.node ? 'node' : ''].filter(Boolean);
   const manualNote = noLine.length ? ` — no install line for this distro: install ${noLine.join(', ')} manually` : '';
   const unmeasured = rgOnPath == null || codexOnPath == null ? ' (other harness tool not measured)' : '';
-  return item('harness-tools', 'manual', `${missing.length ? `${missing.join(' and ')} missing from harness tools` : 'codex requires node'}${nodeEvidence}${unmeasured}${manualNote}`, commands.join(' && ') || undefined);
+  return item('harness-tools', 'manual', `${missing.length ? `${missing.join(' and ')} missing from harness tools` : 'codex requires node'}${nodeEvidence}${unmeasured}${manualNote}${nodeInstruction && commands.length ? ` — ${nodeInstruction}` : ''}`, commands.join(' && ') || nodeInstruction);
 }
 
 function normalizeDir(value: string): string {
@@ -384,7 +377,9 @@ function serviceVersion(deps: ReadinessDeps): ReadinessItem {
     return item('service-version', 'unknown', 'health was not measured');
   }
   if (deps.health === null) {
-    return item('service-version', 'unknown', 'health did not respond; not measured');
+    return deps.serviceFile === null
+      ? item('service-version', 'ok', 'no service installed; nothing to compare')
+      : item('service-version', 'unknown', 'health did not respond; not measured');
   }
   const daemonSha = typeof deps.health.daemonSha === 'string' ? deps.health.daemonSha.trim() : '';
   const revision = (deps.codeRevision ?? '').trim();

package/src/cli/fleet-cli.ts

@@ -0,0 +1,63 @@
+import type { Command } from 'commander';
+import * as ui from '../ui.js';
+import { writeStdoutJson } from './stdout-json.js';
+
+export function registerFleetCommands(program: Command): void {
+  // ── fleet (멀티 인스턴스 통합 뷰 · §10 Control Plane/Fleet) ──
+  const fleetCmd = program.command('fleet')
+    .description('멀티 elanous 인스턴스 통합 뷰(READ-ONLY 연합) — 등록 인스턴스·보유 스토어 매트릭스. `logs instances` 일반화(kubectl get nodes 등가). 연합 조회는 `session list --all-instances` 등.');
+
+  fleetCmd
+    .command('list', { isDefault: true })
+    .description('등록 인스턴스 나열 — name·alive·repo·state-dir·보유 스토어(logs/sessions/tasks/memory)')
+    .option('--json')
+    .action(async (opts: { json?: boolean }) => {
+      const { buildFleetView } = await import('../domains/fleet.js');
+      const view = buildFleetView();
+      if (opts.json) { await writeStdoutJson(JSON.stringify(view, null, 2) + '\n'); return; }
+      ui.header(`Fleet (${view.length} instances · ${view.filter((v) => v.alive).length} alive)`);
+      for (const i of view) {
+        const flag = i.alive ? '●' : '○';
+        const s = i.stores;
+        const stores = [s.logs ? 'logs' : '', s.sessions ? 'sessions' : '', s.tasks ? 'tasks' : '', s.memory ? 'memory' : '', s.opsEvents ? 'ops' : '', s.schedules ? 'sched' : '', s.mandate ? 'mandate' : '', s.frame ? 'frame' : ''].filter(Boolean).join(',');
+        const kindTag = i.kind === 'test' ? ui.dim(' [test]') : '';
+        console.log(`  ${flag} ${i.name.padEnd(24)}${kindTag} ${(i.liveness === 'remote' ? `remote@${i.hostname ?? 'unknown'}` : i.alive ? `pid=${i.pid}` : 'dead').padEnd(11)} [${stores}]`);
+        console.log(ui.dim(`      ${i.stateDir}${i.repoPath ? `  ← ${i.repoPath}` : ''}`));
+      }
+      ui.info(ui.dim('연합 조회: session list · ops status · self recall `--all-instances` · fleet screen `--all`(격리 test 기본 제외·--include-test 로 포함)'));
+    });
+
+  fleetCmd
+    .command('screen')
+    .description('등록 elanous 인스턴스의 PTY 화면 프레임을 read-only로 조회한다')
+    .option('--all', '등록 인스턴스 전체를 연합 조회한다(격리 test 기본 제외)')
+    .option('--include-test', '--all 연합에 격리 test 인스턴스를 포함한다')
+    .option('--json', '구조화된 프레임 행을 출력한다')
+    .action(async (opts: { all?: boolean; includeTest?: boolean; json?: boolean }) => {
+      const { existsSync } = await import('node:fs');
+      const { homedir } = await import('node:os');
+      const { join } = await import('node:path');
+      const { instanceStorePaths, ptyManifestTargets } = await import('../domains/fleet.js');
+      const { listPtyManifestAt } = await import('../pty-shell/pty-manifest.js');
+      const { stripScreenAnsi } = await import('../harness/harness-screen.js');
+      const currentStateDir = process.env.ELANOUS_STATE_DIR?.trim() || join(homedir(), '.elanous');
+      const targets: Array<{ name: string; dbPath: string }> = [];
+      if (opts.all) {
+        // ⭐⭐ 열거는 `ptyManifestTargets`(SSOT) 한 곳이다 — `pty list --all` 과 **같은 함수**를 쓴다.
+        //    ⛔ 여기서 따로 조립하면 두 창구가 조용히 갈린다(2026-07-30 리뷰 must-fix).
+        targets.push(...ptyManifestTargets({ includeTest: opts.includeTest === true }));
+      } else {
+        targets.push({ name: process.env.ELANOUS_INSTANCE_NAME?.trim() || 'prod', dbPath: instanceStorePaths(currentStateDir).frame });
+      }
+      const rows = targets.flatMap((target) => existsSync(target.dbPath)
+        ? listPtyManifestAt(target.dbPath).map((row) => ({ ...row, instance: row.instance || target.name }))
+        : [])
+        .sort((a, b) => a.frameAt - b.frameAt || a.startedAt - b.startedAt || a.id.localeCompare(b.id));
+      if (opts.json) { await writeStdoutJson(JSON.stringify(rows, null, 2) + '\n'); return; }
+      if (rows.length === 0) { console.log('(화면 프레임 없음)'); return; }
+      for (const row of rows) {
+        console.log(`── ${row.instance} · ${row.id} · ${row.kind} · ${new Date(row.frameAt).toISOString()} ──`);
+        console.log(stripScreenAnsi(row.frame));
+      }
+    });
+}