elanous 0.2.0 → 0.2.4

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

@@ -291,16 +291,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 +385,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));
+      }
+    });
+}

package/src/cli/g6a-registration-probe.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { registerLogsCommands } from './logs-cli.js';
+import { registerDocsCommands } from './docs-cli.js';
+import { registerFleetCommands } from './fleet-cli.js';
+
+const root = new Command();
+registerLogsCommands(root);
+registerDocsCommands(root);
+registerFleetCommands(root);
+console.log(JSON.stringify(root.commands.map(command => ({
+  name: command.name(),
+  flags: command.options.map(option => option.flags),
+  children: command.commands.map(child => ({
+    name: child.name(), flags: child.options.map(option => option.flags),
+  })),
+}))));

package/src/cli/git-install-plan.ts

@@ -0,0 +1,51 @@
+export interface GitInstallPlan {
+  command: string[] | null;
+  display: string;
+  needsSudo: boolean;
+  note?: string;
+  /** Commands run before `command`, in order (e.g. `apt-get update` — a fresh image has empty package lists). */
+  preCommands?: string[][];
+  /** The command only starts an installer UI and returns at once (macOS `xcode-select --install`): wait until git appears. */
+  waitForGit?: boolean;
+}
+
+/** Only known package managers are executable; unknown hosts get a manual download link. */
+export function gitInstallPlan({ platform, distro, has, isRoot = false }: {
+  platform: NodeJS.Platform;
+  distro?: string;
+  has: (name: string) => boolean;
+  /** Root (uid 0 — containers) runs the package manager directly; sudo is often not installed there. */
+  isRoot?: boolean;
+}): GitInstallPlan {
+  const manual: GitInstallPlan = { command: null, display: 'Git 설치: https://git-scm.com/downloads', needsSudo: false };
+  if (platform === 'darwin') {
+    // brew finishes in the terminal; xcode-select only opens Apple's installer window and returns immediately.
+    if (has('brew')) return { command: ['brew', 'install', 'git'], display: 'brew install git', needsSudo: false };
+    if (has('xcode-select')) return { command: ['xcode-select', '--install'], display: 'xcode-select --install', needsSudo: false, waitForGit: true, note: '설치 안내 창에서 «설치»를 누르면 끝날 때까지 기다린다.' };
+    return manual;
+  }
+  if (platform === 'win32') {
+    return has('winget')
+      ? { command: ['winget', 'install', '--id', 'Git.Git', '-e', '--source', 'winget'], display: 'winget install --id Git.Git -e --source winget', needsSudo: false }
+      : manual;
+  }
+  if (platform !== 'linux') return manual;
+  const family = distro?.toLowerCase();
+  const manager = family === 'debian' || family === 'ubuntu' ? 'apt-get'
+    : family === 'fedora' || family === 'rhel' || family === 'amzn2023' ? 'dnf'
+      : family === 'arch' ? 'pacman' : family === 'alpine' ? 'apk' : null;
+  if (!manager || !has(manager)) return manual;
+  if (!isRoot && !has('sudo')) return manual;
+  const prefix = isRoot ? [] : ['sudo'];
+  const install = manager === 'pacman' ? [manager, '-S', '--noconfirm', 'git']
+    : manager === 'apk' ? [manager, 'add', 'git']
+      : [manager, 'install', '-y', 'git'];
+  const command = [...prefix, ...install];
+  const preCommands = manager === 'apt-get' ? [[...prefix, 'apt-get', 'update']] : undefined;
+  return {
+    command,
+    display: [...(preCommands ?? []).map((pre) => pre.join(' ')), command.join(' ')].join(' && '),
+    needsSudo: !isRoot,
+    ...(preCommands ? { preCommands } : {}),
+  };
+}

package/src/cli/hooks-cli.ts

@@ -0,0 +1,44 @@
+import type { Command } from 'commander';
+import { startHookReceiver } from '../hooks/receiver.js';
+import { HookQueue } from '../hooks/queue.js';
+import { getSecretAsync, setSecretAsync } from '../nexus/config/secrets/index.js';
+import { getUserConfig } from '../user-config.js';
+
+export function asanaEnabled(raw: unknown = getUserConfig().raw): boolean {
+  const tox = (raw as { tox?: { external?: { asana?: { enabled?: unknown } } } } | undefined)?.tox;
+  return tox?.external?.asana?.enabled === true;
+}
+
+export function registerHooksCommands(program: Command): void {
+  const hooks = program.command('hooks').description('외부 웹훅 수신·재전송');
+  hooks.command('serve').description('웹훅 수신기를 포그라운드에서 실행')
+    .option('--host <host>', '리스닝 주소', '127.0.0.1')
+    .option('--port <port>', '리스닝 포트', '31480')
+    .action(async (opts: { host: string; port: string }) => {
+      const port = Number(opts.port);
+      if (!/^\d+$/.test(opts.port) || !Number.isSafeInteger(port) || port < 1 || port > 65535)
+        throw new Error('invalid hooks port');
+      const secrets = {
+        linear: await getSecretAsync('hooks.linear'), asana: await getSecretAsync('hooks.asana'),
+        // 첫 핸드셰이크의 비밀을 저장하는 것은 «먼저 온 사람이 이긴다» — Asana 를 켠 설치에서만 연다.
+        ...(asanaEnabled() ? { saveAsana: (value: string) => setSecretAsync('hooks.asana', value) } : {}),
+      };
+      const server = startHookReceiver({ host: opts.host, port, secrets });
+      console.log(`hooks listening ${new URL(server.url).host}`);
+      await new Promise<void>(resolve => {
+        const stop = () => {
+          process.removeListener('SIGINT', stop);
+          process.removeListener('SIGTERM', stop);
+          server.stop();
+          resolve();
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+      });
+    });
+  hooks.command('status').description('대기 중인 웹훅 수와 마지막 전달 시각')
+    .action(() => {
+      const queue = new HookQueue();
+      console.log(JSON.stringify({ queued: queue.count(), lastDelivered: queue.lastDelivered() }));
+    });
+}

package/src/cli/ingest-token-cli.ts

@@ -0,0 +1,21 @@
+import type { Command } from 'commander';
+import { issueIngestToken, listIngestTokens, revokeIngestToken } from '../nexus/api/ingest-token.js';
+
+export function registerIngestTokenCommands(nexus: Command): void {
+  const token = nexus.command('ingest-token').description('Manage POST /v1/tasks-only bearer tokens');
+  token.command('issue <name>').description('Issue a token; print its secret exactly once')
+    .action((name: string) => {
+      try { process.stdout.write(`${issueIngestToken(name).token}\n`); }
+      catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+    });
+  token.command('revoke <name>').description('Revoke a token by name')
+    .action((name: string) => {
+      try { if (!revokeIngestToken(name)) throw new Error(`ingest token not found: ${name}`); }
+      catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+    });
+  token.command('list').description('List token names and issuance times (never secrets)')
+    .action(() => {
+      try { for (const row of listIngestTokens()) process.stdout.write(`${row.name}\t${row.createdAt}\n`); }
+      catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+    });
+}