elanous 0.2.0 → 0.2.4

package/src/agent-mission/pr-review-watch.ts

@@ -100,6 +100,35 @@ export function pickLatestSignal(raw: RawReviews): ReviewSignal | null {
 // ──────────────────── IO (gh 폴링·상태 db) ──────────────────────────────
 
 export type RunGh = (args: string[]) => string;
+
+export type ReviewWatchGhErrorKind = 'auth' | 'not-found' | 'missing-binary' | 'other';
+
+export class ReviewWatchGhError extends Error {
+  readonly name = 'ReviewWatchGhError';
+
+  constructor(readonly kind: ReviewWatchGhErrorKind, message: string, cause?: unknown) {
+    super(message, { cause });
+  }
+}
+
+/** gh CLI 실패의 stderr와 spawn 오류를 구분한다. 분류 이외의 호출/재시도 정책은 호출부가 결정한다. */
+export function classifyReviewWatchGhError(error: unknown): ReviewWatchGhError {
+  if (error instanceof ReviewWatchGhError) return error;
+  const details = error && typeof error === 'object' ? error as { message?: unknown; stderr?: unknown; code?: unknown } : {};
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : String(error);
+  const stderr = details.stderr == null ? '' : String(details.stderr);
+  const text = `${stderr}\n${message}`;
+  let kind: ReviewWatchGhErrorKind = 'other';
+  if (details.code === 'ENOENT' || /\b(?:gh:\s*)?command not found\b|\bgh:\s*not found\b|\bspawn gh ENOENT\b|\bexecutable file not found\b/i.test(text)) {
+    kind = 'missing-binary';
+  } else if (/\b401\b|\bunauthorized\b|\bbad credentials\b|\bnot logged in\b|\bgh auth login\b|\bauthenticat(?:e|ion)\b/i.test(text)) {
+    kind = 'auth';
+  } else if (/\b404\b|\bnot found\b/i.test(text)) {
+    kind = 'not-found';
+  }
+  return new ReviewWatchGhError(kind, stderr.trim() || message, error);
+}
+
 // env: process.env — cron/launchd 최소 PATH 에서도 ensure-bin-path 가 보강한 PATH 로 gh(/opt/homebrew/bin)를
 // 찾도록 명시 전달(Bun 은 env 미전달 시 startup 스냅샷 PATH 로 해석 → 무음실패).
 const defaultRunGh: RunGh = (args) => execFileSync('gh', args, { encoding: 'utf-8', timeout: 60_000, maxBuffer: 20 * 1024 * 1024, env: process.env });
@@ -124,7 +153,7 @@ export function setLastReviewKey(db: Database, pr: string, key: string, now: str
     [pr, key, now]);
 }
 
-/** opt-in 라벨이 붙은 열린 PR 번호 목록(READ-ONLY 배치). 실패=[]. */
+/** opt-in 라벨이 붙은 열린 PR 번호 목록(READ-ONLY 배치). 조회 실패는 분류해 전달한다. */
 export function fetchLabeledOpenPrs(label: string, deps: { runGh?: RunGh } = {}): string[] {
   const runGh = deps.runGh ?? defaultRunGh;
   try {
@@ -134,8 +163,9 @@ export function fetchLabeledOpenPrs(label: string, deps: { runGh?: RunGh } = {})
   } catch (e) {
     // ⚠️ gh 실패를 무음으로 []로 삼키면 (gh not-in-PATH·auth·network) 라벨 PR 이 항상 0 으로 보여 파이프라인이
     //   조용히 사문화된다(이 버그의 근본). 반드시 관측을 남긴다 — 조회 0 이 '진짜 0' 인지 'gh 실패' 인지 구분.
-    debug.log('review-watch', 'list-prs-error', { label, error: (e as Error).message }, { level: 'error' });
-    return [];
+    const error = classifyReviewWatchGhError(e);
+    debug.log('review-watch', 'list-prs-error', { label, error: error.message, kind: error.kind }, { level: 'error' });
+    throw error;
   }
 }
 
@@ -176,13 +206,13 @@ export function analyzeSignals(raw: RawReviews): SignalAnalysis {
   return { latest: pickLatestSignal(raw), latestHuman: pickLatestHumanSignal(raw) };
 }
 
-/** PR 신호 분석 조회(READ-ONLY). 실패=신호 없음·사람 리뷰 없음. */
+/** PR 신호 분석 조회(READ-ONLY). 조회 실패는 분류해 전달한다. */
 export function fetchSignalAnalysis(pr: string, deps: { runGh?: RunGh } = {}): SignalAnalysis {
   const runGh = deps.runGh ?? defaultRunGh;
   try {
     return analyzeSignals(JSON.parse(runGh(['pr', 'view', pr, '--json', 'reviews,comments'])) as RawReviews);
-  } catch {
-    return { latest: null, latestHuman: null };
+  } catch (e) {
+    throw classifyReviewWatchGhError(e);
   }
 }
 
@@ -208,8 +238,9 @@ export interface PrReviewWatchDeps {
 
 export interface PrReviewWatchOutcome {
   pr: string;
-  /** triggered=발동함 · initial-review-failed=초기리뷰 시도 후 null 반환 · initial-review-error=초기리뷰 예외 · dedup=이미 처리한 리뷰 · bot=자동신호 skip · none=신호없음 · capped=발동한도 초과 대기. */
-  status: 'triggered' | 'initial-review-failed' | 'initial-review-error' | 'dedup' | 'bot' | 'none' | 'capped';
+  /** triggered=발동함 · signal-error=해당 PR 신호 조회 실패 · initial-review-failed=초기리뷰 시도 후 null 반환 · initial-review-error=초기리뷰 예외 · dedup=이미 처리한 리뷰 · bot=자동신호 skip · none=신호없음 · capped=발동한도 초과 대기. */
+  status: 'triggered' | 'signal-error' | 'initial-review-failed' | 'initial-review-error' | 'dedup' | 'bot' | 'none' | 'capped';
+  error?: ReviewWatchGhErrorKind;
   reviewKey?: string;
   result?: ReviewLoopResult | null;
 }
@@ -217,7 +248,7 @@ export interface PrReviewWatchOutcome {
 const defaultTrigger = (pr: string, opts: ReviewLoopOpts) => runReviewLoop(pr, opts);
 
 /** 감시 1사이클 — 라벨 PR 폴링 → 새 사람 리뷰 감지 → runReviewLoop 발동(사이클당 maxTriggers 건). */
-export async function runPrReviewWatchCycle(deps: PrReviewWatchDeps = {}): Promise<PrReviewWatchOutcome[]> {
+export async function runPrReviewWatchCycle(deps: PrReviewWatchDeps = {}): Promise<PrReviewWatchOutcome[] & { authErrors: number }> {
   const db = deps.db ?? openPrReviewWatchDb();
   const ownDb = !deps.db;
   const now = deps.now?.() ?? new Date().toISOString();
@@ -229,8 +260,16 @@ export async function runPrReviewWatchCycle(deps: PrReviewWatchDeps = {}): Promi
 
   const outcomes: PrReviewWatchOutcome[] = [];
   let triggered = 0;
+  let authErrors = 0;
   try {
-    const prs = fetchLabeledOpenPrs(label, ghDep);
+    let prs: string[];
+    try {
+      prs = fetchLabeledOpenPrs(label, ghDep);
+    } catch (e) {
+      const error = classifyReviewWatchGhError(e);
+      debug.log('review-watch', 'cycle-failed', { label, error: error.kind }, { level: 'error' });
+      throw error;
+    }
     const rework = resolveReworkBackendChoice(reviewLoopOpts);
     debug.log('review-watch', 'cycle-start', {
       label, prs: prs.length, maxTriggers,
@@ -239,7 +278,17 @@ export async function runPrReviewWatchCycle(deps: PrReviewWatchDeps = {}): Promi
     });
 
     for (const pr of prs) {
-      const { latest, latestHuman } = fetchSignalAnalysis(pr, ghDep);
+      let analysis: SignalAnalysis;
+      try {
+        analysis = fetchSignalAnalysis(pr, ghDep);
+      } catch (e) {
+        const error = classifyReviewWatchGhError(e);
+        if (error.kind === 'auth') authErrors++;
+        debug.log('review-watch', 'signal-error', { pr, kind: error.kind, error: error.message }, { level: 'error' });
+        outcomes.push({ pr, status: 'signal-error', error: error.kind });
+        continue;
+      }
+      const { latest, latestHuman } = analysis;
       // ★ 트리거 판정은 '최신 미처리 사람 신호(latestHuman)' 기준 — 봇/자기 자동 신호는 무시한다.
       //   ⚠️ self-dev PR 은 내부 리뷰노드/자동 코멘트를 gh 인증 계정(사람 계정)으로 남겨 봇 신호(마커)를
       //   갖는다. '최신 절대 신호'로 판정하면 (a) 봇 신호가 최신이라 skip-bot dead-end(triggered=0 상시의
@@ -308,8 +357,8 @@ export async function runPrReviewWatchCycle(deps: PrReviewWatchDeps = {}): Promi
       debug.log('review-watch', 'triggered', { pr, reviewKey: latestHuman.key, action: result?.action ?? 'error' });
       outcomes.push({ pr, status: 'triggered', reviewKey: latestHuman.key, result });
     }
-    debug.log('review-watch', 'cycle-done', { label, scanned: prs.length, triggered });
-    return outcomes;
+    debug.log('review-watch', 'cycle-done', { label, scanned: prs.length, triggered, authErrors });
+    return Object.assign(outcomes, { authErrors });
   } finally {
     if (ownDb) db.close();
   }

package/src/agent-mission/resource-ladder.ts

@@ -0,0 +1,187 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { streamLLM } from '../llm.js';
+import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
+import { OFFICIAL_INDEX_KEYS } from '../market/official-keys.js';
+import { verifyIndex, type MarketplaceIndex } from '../market/signed-index.js';
+import { buildCapabilityMatrix, pickBackend, type CapabilityReaders } from './capability-matrix.js';
+import { createCapabilityReaders } from './capability-readers.js';
+import { normalizeServiceName } from './capability-types.js';
+import { discoverCapability, type CapabilityCandidate } from './discover-capability.js';
+import { ELANOUS_MARKET_URL } from '../plugins/install/market-fetch.js';
+
+const MARKETPLACE = 'elanous';
+const INDEX_URL = new URL('marketplace.json', ELANOUS_MARKET_URL).href; // one source of truth for the official market
+const MAX_NEEDS = 5;
+
+export interface ResourcePlan {
+  needs: string[];
+  have: string[];
+  plugin?: { plugin: string; marketplace: string; source: 'official-index' };
+  backend?: { name: string; why: string };
+  gaps: Array<{ need: string; candidates: CapabilityCandidate[] }>;
+  decisions: string[];
+}
+
+export interface MissionResources {
+  readonly backend?: string;
+  readonly plugin?: string;
+  readonly resources?: 'off' | 'on';
+}
+
+export interface ResourceLadderDeps extends MissionResources {
+  /** One JSON-producing LLM call; the raw mission is never sent to logs. */
+  readonly inferNeeds?: (safeMission: string) => Promise<string>;
+  readonly readers?: CapabilityReaders;
+  /** Read the official index and its detached signature as a pair; no other market is consulted. */
+  readonly readOfficialIndex?: () => Promise<{ marketplaceBytes: Uint8Array; signatureText: string }>;
+  /** Installed Elanous plugin ledger, not the available-market catalog. */
+  readonly readInstalledPlugins?: () => readonly { name: string; market: string }[];
+  readonly discover?: typeof discoverCapability;
+  /** Optional PTY integration seam (the planner never creates a PTY or installs by itself). */
+  readonly installPlugin?: (request: { plugin: string; marketplace: string }) => Promise<unknown>;
+  readonly decide?: (event: DecisionEvent) => unknown;
+  readonly log?: (step: string, data: Record<string, unknown>) => void;
+}
+
+function safeMissionText(mission: string): string {
+  return mission
+    .replace(/\b(?:api[_-]?key|token|password|secret|authorization)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, '[redacted]')
+    .replace(/\b(?:bearer\s+)?(?:sk-[\w-]+|gh[pousr]_[\w-]+|github_pat_[\w-]+|AIza[\w-]+|xox[baprs]-[\w-]+)/gi, '[redacted]')
+    .replace(/https?:\/\/\S+/gi, '[url]');
+}
+
+function safeNeed(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const need = value.normalize('NFKC').trim();
+  if (!need || need.length > 80 || /[\n\r{}<>@=:/\\]|(?:secret|password|token|api.?key|bearer|redacted)/i.test(need)) return null;
+  return need;
+}
+
+function parseNeeds(raw: string): string[] {
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return []; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray((parsed as { needs?: unknown }).needs)) return [];
+  const needs: string[] = [];
+  for (const item of (parsed as { needs: unknown[] }).needs) {
+    const need = safeNeed(item);
+    if (need && !needs.some(existing => normalizeServiceName(existing) === normalizeServiceName(need))) needs.push(need);
+    if (needs.length === MAX_NEEDS) break;
+  }
+  return needs;
+}
+
+async function inferNeeds(mission: string): Promise<string> {
+  return streamLLM([
+    { role: 'system', content: 'Identify at most five concrete tool/service/skill capabilities required for this mission. Reply ONLY with JSON {"needs":["capability"]}. No credentials, tokens, URLs, or mission text in the output. If uncertain, return an empty list.' },
+    { role: 'user', content: mission },
+  ], () => {}, { maxTokens: 200, temperature: 0 });
+}
+
+async function readOfficialIndex(): Promise<{ marketplaceBytes: Uint8Array; signatureText: string }> {
+  const [index, signature] = await Promise.all([fetch(INDEX_URL), fetch(new URL('index.sig', INDEX_URL))]);
+  if (!index.ok || !signature.ok) throw new Error('official index unavailable');
+  return { marketplaceBytes: new Uint8Array(await index.arrayBuffer()), signatureText: await signature.text() };
+}
+
+function installedPlugins(): readonly { name: string; market: string }[] {
+  try {
+    const rows: unknown = JSON.parse(readFileSync(join(elanousStateRoot(), 'plugins', 'installed.json'), 'utf8'));
+    if (!Array.isArray(rows)) return [];
+    return rows.flatMap((row): { name: string; market: string }[] => row && typeof row === 'object'
+      && typeof row.name === 'string' && typeof row.market === 'string' ? [{ name: row.name, market: row.market }] : []);
+  } catch { return []; }
+}
+
+function matches(need: string, labels: readonly string[]): boolean {
+  const key = normalizeServiceName(need);
+  return !!key && labels.some(label => normalizeServiceName(label) === key);
+}
+
+function pluginLabels(plugin: MarketplaceIndex['plugins'][number]): string[] {
+  return [plugin.name, plugin.description ?? '', ...plugin['ai.elanous'].capabilities, ...(plugin['ai.elanous'].vocab ?? [])];
+}
+
+/** Pre-mission resource judgment. Only the optional, injected installer can cause installation. */
+export async function planMissionResources(mission: string, deps: ResourceLadderDeps = {}, options: MissionResources = {}): Promise<ResourcePlan> {
+  const plan: ResourcePlan = { needs: [], have: [], gaps: [], decisions: [] };
+  if (options.resources === 'off' || deps.resources === 'off') return plan;
+  const backend = options.backend ?? deps.backend;
+  const plugin = options.plugin ?? deps.plugin;
+  const decide = (step: string, kind: DecisionEvent['kind'], what: string, why: string) => {
+    plan.decisions.push(`${step}: ${what} — ${why}`);
+    (deps.decide ?? emitDecision)({ kind, what, reason: why, purpose: 'pre-mission resource selection', target: 'agent-mission', phase: 'dispatch' });
+    (deps.log ?? ((event, data) => debug.log('agent-mission.resources', event, data)))(step, { kind, what, why });
+  };
+
+  try { plan.needs = parseNeeds(await (deps.inferNeeds ?? inferNeeds)(safeMissionText(mission))); }
+  catch { decide('needs', 'ESCALATE', '능력 판정 불가', 'LLM 응답 실패 — 추측하지 않음'); }
+  decide('needs', 'VERIFY', '필요 능력 판정', `${plan.needs.length}개 확인`);
+  if (!plan.needs.length) return plan;
+
+  let matrix: ReturnType<typeof buildCapabilityMatrix> = [];
+  try { matrix = buildCapabilityMatrix(deps.readers ?? createCapabilityReaders()); }
+  catch { decide('have', 'ESCALATE', '능력표 읽기 실패', 'ready 로 확인되지 않은 서비스는 보유로 세지 않음'); }
+  const ready = matrix.filter(entry => entry.state === 'ready');
+  let remaining = plan.needs.filter(need => {
+    if (!ready.some(entry => matches(need, [entry.service]))) return true;
+    plan.have.push(need);
+    return false;
+  });
+  decide('have', 'VERIFY', 'ready 서비스 대조', `${plan.have.length}개 확인`);
+
+  let index: MarketplaceIndex | undefined;
+  if (remaining.length) {
+    try {
+      const pair = await (deps.readOfficialIndex ?? readOfficialIndex)();
+      const checked = verifyIndex({ ...pair, trustedKeys: OFFICIAL_INDEX_KEYS });
+      if (checked.ok && checked.index.name === MARKETPLACE) index = checked.index;
+      else decide('official-index', 'ESCALATE', '공식 마켓 거부', '서명 또는 마켓 이름 검증 실패');
+    } catch { decide('official-index', 'ESCALATE', '공식 마켓 조회 실패', '서명 검증 가능한 원본 인덱스 없음'); }
+  }
+  if (index) {
+    let installed: readonly { name: string; market: string }[] = [];
+    try { installed = (deps.readInstalledPlugins ?? installedPlugins)(); }
+    catch { decide('have', 'ESCALATE', '설치 원장 읽기 실패', '설치된 스킬을 보유로 간주하지 않음'); }
+    remaining = remaining.filter(need => {
+      if (!index.plugins.some(entry => installed.some(row => row.market === MARKETPLACE && row.name === entry.name)
+        && matches(need, pluginLabels(entry)))) return true;
+      plan.have.push(need);
+      return false;
+    });
+    decide('have', 'VERIFY', '설치된 플러그인 스킬 대조', `${plan.have.length}개 확인`);
+    if (!plugin) {
+      const choices = index.plugins.filter(entry => remaining.some(need => matches(need, pluginLabels(entry))));
+      if (choices.length === 1) {
+        plan.plugin = { plugin: choices[0]!.name, marketplace: MARKETPLACE, source: 'official-index' };
+        decide('official-index', 'ROUTE', '공식 플러그인 선택', '서명 검증된 인덱스에서 일치하는 플러그인 한 개');
+        if (deps.installPlugin) {
+          try {
+            const result = await deps.installPlugin({ plugin: plan.plugin.plugin, marketplace: MARKETPLACE });
+            const installed = result && typeof result === 'object' && 'outcome' in result && result.outcome === 'installed';
+            if (installed) remaining = remaining.filter(need => !matches(need, pluginLabels(choices[0]!)));
+            decide('official-index', installed ? 'VERIFY' : 'ESCALATE', '플러그인 설치 요청 결과', installed ? '설치 성공 확인' : '설치 미확인 — 필요 능력을 미충족으로 유지');
+          } catch { decide('official-index', 'ESCALATE', '플러그인 설치 실패', '설치 결과를 보유로 간주하지 않음'); }
+        } else decide('official-index', 'ESCALATE', '플러그인 제안만 함', '설치기 없음 — 필요 능력을 미충족으로 유지');
+      } else if (choices.length > 1) decide('official-index', 'ESCALATE', '플러그인 선택 보류', '공식 후보가 둘 이상이라 자동 선택하지 않음');
+    } else decide('official-index', 'ROUTE', '명시 플러그인 보존', '호출자 선택을 덮지 않음');
+  }
+
+  for (const need of remaining) {
+    let candidates: CapabilityCandidate[] = [];
+    try { candidates = await (deps.discover ?? discoverCapability)(need, { community: false }); }
+    catch { decide('discover', 'ESCALATE', '발굴 실패', '후보 없음 — 자동 설치하지 않음'); }
+    plan.gaps.push({ need, candidates });
+    decide('discover', 'ESCALATE', '미충족 능력 후보', `${candidates.length}개 후보 제안만 함`);
+  }
+  if (!backend) {
+    const chosen = plan.needs.map(need => ({ need, name: pickBackend(matrix, need) })).find(row => row.name);
+    if (chosen?.name) {
+      plan.backend = { name: chosen.name, why: '필요 서비스의 ready 관측에 따른 선택' };
+      decide('backend', 'ROUTE', 'ready 에이전트 선택', plan.backend.why);
+    } else decide('backend', 'ESCALATE', '에이전트 자동 선택 보류', '필요 서비스의 ready 관측 없음');
+  } else decide('backend', 'ROUTE', '명시 에이전트 보존', '호출자 backend 를 덮지 않음');
+  return plan;
+}

package/src/agent-mission/tool-install.ts

@@ -0,0 +1,249 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { detectDistroFamily, toolInstallLine, type DistroFamily } from '../cli/doctor-distro.js';
+import { debug } from '../debug/log.js';
+import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
+
+type RemedyTool = 'gh' | 'rg' | 'node' | 'codex' | 'jq' | 'ffmpeg';
+export type SmokeTool = RemedyTool | 'git';
+
+export const SMOKE_CHECKS: Record<SmokeTool, { cmd: string[]; stdin?: string; expect: RegExp }> = {
+  jq: { cmd: ['jq', '.a'], stdin: '{"a":1}', expect: /^1$/ },
+  rg: { cmd: ['rg', '-c', 'x'], stdin: 'x\n', expect: /^1$/ },
+  node: { cmd: ['node', '-e', 'console.log(1+1)'], expect: /^2$/ },
+  ffmpeg: { cmd: ['ffmpeg', '-hide_banner', '-f', 'lavfi', '-i', 'nullsrc=s=16x16:d=0.1', '-f', 'null', '-'], expect: /^[\s\S]*$/ },
+  gh: { cmd: ['gh', 'help'], expect: /^[\s\S]*$/ },
+  codex: { cmd: ['codex', '--help'], expect: /^[\s\S]*$/ },
+  git: { cmd: ['git', 'init', '-q'], expect: /^[\s\S]*$/ },
+};
+
+type ExecResult = { status: number | null; stdout?: string; stderr?: string };
+type PtyProbe = { status: 'ok'; output: string; exitCode: number } | { status: 'unavailable'; detail: string };
+export interface SmokeDeps {
+  exec?: (cmd: string[], opts: { stdin?: string; timeoutMs: number }) => ExecResult;
+}
+
+function defaultExec(cmd: string[], opts: { stdin?: string; timeoutMs: number }): ExecResult {
+  const result = spawnSync(cmd[0]!, cmd.slice(1), {
+    input: opts.stdin, timeout: opts.timeoutMs, encoding: 'utf8',
+  });
+  return { status: (result.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT' ? 127 : result.status, stdout: result.stdout ?? '', stderr: (result.stderr ?? '') + (result.error ? String(result.error) : '') };
+}
+
+/** Verify a small real operation, not just the executable's version string. */
+export function smokeCheck(tool: SmokeTool, deps: SmokeDeps = {}): { ok: boolean; detail: string; unavailable?: boolean } {
+  const check = SMOKE_CHECKS[tool];
+  let directory: string | undefined;
+  try {
+    const cmd = [...check.cmd];
+    if (tool === 'git') {
+      directory = mkdtempSync(join(tmpdir(), 'elanous-git-smoke-'));
+      cmd.push(join(directory, 'repo'));
+    }
+    const result = (deps.exec ?? defaultExec)(cmd, { ...(check.stdin === undefined ? {} : { stdin: check.stdin }), timeoutMs: 20_000 });
+    const output = (result.stdout ?? '').trim();
+    if (result.status === null) return { ok: false, unavailable: true, detail: `${tool} smoke unavailable: ${(result.stderr ?? 'no exit status').slice(-400)}` };
+    const ok = result.status === 0 && check.expect.test(output);
+    return { ok, detail: ok ? `${tool} smoke passed` : `${tool} smoke failed (exit ${result.status}): ${((result.stderr ?? '').trim() || output || 'no output').slice(-400)}` };
+  } catch (error) {
+    return { ok: false, unavailable: true, detail: `${tool} smoke unavailable: ${error instanceof Error ? error.message : String(error)}` };
+  } finally {
+    if (directory) rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+export interface ToolInstallDeps extends SmokeDeps {
+  typeLine?: (ptyRef: string, line: string) => void | Promise<void>;
+  waitIdle?: (ptyRef: string, opts: { timeoutMs: number; completionMarker?: string }) => string | Promise<string>;
+  /** Override only the decision side effect; default publishes to the live decision stream. */
+  decision?: (event: DecisionEvent) => void;
+  /** Override only the observation side effect. */
+  log?: (event: 'checked' | 'typed' | 'installed' | 'escalated' | 'failed', data: Record<string, unknown>) => void;
+}
+
+export type ToolInstallResult = {
+  outcome: 'already' | 'installed' | 'escalate' | 'failed';
+  line?: string;
+  reason: string;
+  needsLogin?: boolean;
+};
+
+const cliPath = resolve(import.meta.dir, '../../bin/elanous.mjs');
+function runPtyCli(args: string[]): string {
+  const scope = process.env.NODE_ENV === 'test' || process.env.ELANOUS_HARNESS_SPACE_ID ? ['--test'] : [];
+  const result = spawnSync(process.execPath, [cliPath, ...scope, ...args], { encoding: 'utf8', timeout: 30_000 });
+  if (result.status !== 0) throw new Error((result.stderr ?? '').trim() || `pty ${args[0]} exited ${result.status}`);
+  return result.stdout ?? '';
+}
+
+function defaultTypeLine(ptyRef: string, line: string): void {
+  runPtyCli(['pty', 'text', ptyRef, line, '--enter', '--actor', 'agent']);
+}
+
+export async function waitForPtyCompletion(
+  ptyRef: string,
+  opts: { timeoutMs: number; completionMarker?: string },
+  snapshot: (ref: string) => string | Promise<string>,
+): Promise<string> {
+  if (!opts.completionMarker) throw new Error('PTY completion marker required');
+  const deadline = Date.now() + opts.timeoutMs;
+  const completed = new RegExp(`(?:^|\\n)${opts.completionMarker}[0-9]+(?:\\r?\\n|$)`);
+  let last = '';
+  while (Date.now() < deadline) {
+    last = await snapshot(ptyRef);
+    if (completed.test(last.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''))) return last;
+    await new Promise<void>((done) => setTimeout(done, Math.min(500, Math.max(0, deadline - Date.now()))));
+  }
+  throw new Error(`PTY completion timeout: ${screenTail(last)}`);
+}
+
+function defaultWaitIdle(ptyRef: string, opts: { timeoutMs: number; completionMarker?: string }): Promise<string> {
+  return waitForPtyCompletion(ptyRef, opts, (ref) => runPtyCli(['pty', 'snapshot', ref]).replace(/^PtyShellSnapshot[^\n]*\n/, ''));
+}
+
+function screenTail(snapshot: string): string {
+  return snapshot.trim().split(/\r?\n/).slice(-5).join(' | ').slice(-400) || 'empty PTY snapshot';
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+export async function probeInPty(ptyRef: string, invocation: string, deps: Pick<ToolInstallDeps, 'typeLine' | 'waitIdle'> = {}): Promise<PtyProbe> {
+  const marker = `ELANOUS_SMOKE_${randomUUID().replace(/-/g, '')}`;
+  const line = `smoke_output=$(${invocation} 2>&1); smoke_rc=$?; printf '%s\\n' ${shellQuote(`${marker}_START`)}; printf '%s\\n' "$smoke_output" | tail -c 400; printf '\\n%s%s\\n' ${shellQuote(`${marker}_END_`)} "$smoke_rc"`;
+  try {
+    await (deps.typeLine ?? defaultTypeLine)(ptyRef, line);
+    const snapshot = (await (deps.waitIdle ?? defaultWaitIdle)(ptyRef, { timeoutMs: 20_000, completionMarker: `${marker}_END_` })).replace(/\r\n/g, '\n').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+    const startToken = `${marker}_START\n`;
+    const startAt = snapshot.indexOf(`\n${startToken}`);
+    const start = startAt < 0 ? (snapshot.startsWith(startToken) ? 0 : -1) : startAt + 1;
+    const endToken = `\n${marker}_END_`;
+    const end = start < 0 ? -1 : snapshot.indexOf(endToken, start + startToken.length);
+    const status = end < 0 ? undefined : /^([0-9]+)(?:\n|$)/.exec(snapshot.slice(end + endToken.length))?.[1];
+    if (status === undefined) return { status: 'unavailable', detail: `PTY probe missing exit marker: ${screenTail(snapshot)}` };
+    return { status: 'ok', exitCode: Number(status), output: snapshot.slice(start + startToken.length, end).trim() };
+  } catch (error) {
+    return { status: 'unavailable', detail: `PTY probe unavailable: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+/** Execute an install line in the existing PTY and read its completion marker, not the shell prompt. */
+export async function executeInstallInPty(
+  ptyRef: string, line: string, deps: Pick<ToolInstallDeps, 'typeLine' | 'waitIdle'> = {},
+  onTyped?: () => void,
+): Promise<{ exitCode: number; snapshot: string }> {
+  const marker = `ELANOUS_INSTALL_${randomUUID().replace(/-/g, '')}_END_`;
+  await (deps.typeLine ?? defaultTypeLine)(ptyRef, `${line}; install_rc=$?; printf '\\n%s%s\\n' ${shellQuote(marker)} "$install_rc"`);
+  onTyped?.();
+  const snapshot = await (deps.waitIdle ?? defaultWaitIdle)(ptyRef, { timeoutMs: 300_000, completionMarker: marker });
+  const exitCode = new RegExp(`(?:^|\\n)${marker}([0-9]+)(?:\\r?\\n|$)`).exec(snapshot.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''))?.[1];
+  if (exitCode === undefined) throw new Error(`PTY install missing exit marker: ${screenTail(snapshot)}`);
+  return { exitCode: Number(exitCode), snapshot };
+}
+
+/** Both probes run in the installation shell: the agent process may have a different PATH. */
+// git is checked on the host only (doctor --fix); installMissingTool never takes it.
+async function smokeInPty(tool: RemedyTool, ptyRef: string, deps: ToolInstallDeps): Promise<{ ok: boolean; detail: string; unavailable?: boolean }> {
+  const check = SMOKE_CHECKS[tool];
+  const command = check.cmd.map(shellQuote).join(' ');
+  const invocation = check.stdin === undefined ? command : `printf %s ${shellQuote(check.stdin)} | ${command}`;
+  const result = await probeInPty(ptyRef, invocation, deps);
+  if (result.status === 'unavailable') return { ok: false, unavailable: true, detail: `${tool} ${result.detail}` };
+  const ok = result.exitCode === 0 && check.expect.test(result.output);
+  return { ok, detail: ok ? `${tool} smoke passed` : `${tool} smoke failed (exit ${result.exitCode}): ${result.output.slice(-400) || 'no output'}` };
+}
+
+/** A known, unprivileged prescription is typed in the existing shell; sudo and unknown remedies remain human decisions. */
+export async function installMissingTool(
+  { tool, family: suppliedFamily, ptyRef }: { tool: RemedyTool; family?: DistroFamily; ptyRef: string },
+  deps: ToolInstallDeps = {},
+): Promise<ToolInstallResult> {
+  let family: DistroFamily = suppliedFamily ?? 'unknown';
+  const log = (event: 'checked' | 'typed' | 'installed' | 'escalated' | 'failed', outcome: ToolInstallResult['outcome'] | 'missing' | 'pending', reason: string) =>
+    (deps.log ?? ((name, data) => debug.log('agent-mission.install', name, data)))(event, { tool, family, outcome, reason });
+  const decide = deps.decision ?? emitDecision;
+  const probe = () => deps.exec ? Promise.resolve(smokeCheck(tool, deps)) : smokeInPty(tool, ptyRef, deps);
+  const codexLogin = async (outcome: 'already' | 'installed', reason: string, line?: string): Promise<ToolInstallResult> => {
+    if (tool !== 'codex') return { outcome, reason, ...(line ? { line } : {}) };
+    let auth: PtyProbe;
+    if (deps.exec) {
+      try {
+        const result = deps.exec(['codex', 'login', 'status'], { timeoutMs: 20_000 });
+        auth = result.status === null
+          ? { status: 'unavailable', detail: result.stderr ?? 'codex login status unavailable' }
+          : { status: 'ok', exitCode: result.status, output: `${result.stdout ?? ''}\n${result.stderr ?? ''}` };
+      } catch (error) {
+        auth = { status: 'unavailable', detail: String(error) };
+      }
+    } else auth = await probeInPty(ptyRef, "'codex' 'login' 'status'", deps);
+    if (auth.status === 'ok' && auth.exitCode === 0 && /logged in/i.test(auth.output) && !/not logged in/i.test(auth.output)) {
+      return { outcome, reason, ...(line ? { line } : {}) };
+    }
+    const loginReason = `codex authentication not verified; run codex login before authenticated work${auth.status === 'unavailable' ? ` (${auth.detail})` : ''}`;
+    decide({ kind: 'ESCALATE', what: 'codex 로그인 필요', reason: loginReason, purpose: '인증 상태를 사람이 확인한다', target: 'human' });
+    log('escalated', 'escalate', loginReason);
+    return { outcome: 'escalate', reason: loginReason, ...(line ? { line } : {}), needsLogin: true };
+  };
+  const checked = await probe();
+  log('checked', checked.ok ? 'already' : checked.unavailable ? 'failed' : 'missing', checked.detail);
+  if (checked.unavailable) {
+    log('failed', 'failed', checked.detail);
+    return { outcome: 'failed', reason: checked.detail };
+  }
+  if (checked.ok) {
+    decide({ kind: 'VERIFY', what: `${tool} 설치 확인`, reason: checked.detail, purpose: '이미 동작하므로 설치를 생략한다', target: 'shell' });
+    return codexLogin('already', checked.detail);
+  }
+  if (suppliedFamily === undefined) {
+    // No `case … )` here: the probe runs inside `$( … )`, and bash 3.2 (macOS /bin/sh) reads that `)` as the end of it.
+    const distro = await probeInPty(ptyRef, `uname -s; if [ -r /etc/os-release ]; then grep -E '^(ID|ID_LIKE|VERSION_ID)=' /etc/os-release; fi; true`, deps);
+    if (distro.status === 'unavailable') {
+      log('failed', 'failed', distro.detail);
+      return { outcome: 'failed', reason: distro.detail };
+    }
+    if (distro.exitCode === 0) {
+      const [platform, ...release] = distro.output.split('\n');
+      family = detectDistroFamily(platform === 'Darwin' ? 'darwin' : platform === 'Linux' ? 'linux' : undefined, release.join('\n'));
+    }
+  }
+  const line = toolInstallLine(tool, family);
+  if (!line || /\bsudo\b/.test(line)) {
+    const reason = line ? 'sudo-is-human' : 'no-remedy';
+    decide({ kind: 'ESCALATE', what: `${tool} 설치는 사람이 필요`, reason: line ?? reason, purpose: '사람의 설치 판단을 받는다', target: 'human' });
+    log('escalated', 'escalate', reason);
+    return { outcome: 'escalate', ...(line ? { line } : {}), reason, ...(tool === 'codex' ? { needsLogin: true } : {}) };
+  }
+  decide({ kind: 'ROUTE', what: `${tool} 없음 → 설치`, reason: line, purpose: '가장 낮은 칸으로 끝낸다', target: 'shell' });
+  let snapshot = '';
+  try {
+    const result = await executeInstallInPty(ptyRef, line, deps, () => log('typed', 'pending', line));
+    snapshot = result.snapshot;
+    const exitCode = String(result.exitCode);
+    const verified = await probe();
+    decide({ kind: 'VERIFY', what: `${tool} 설치 확인`, reason: verified.detail, purpose: '가장 작은 진짜 일을 확인한다', target: 'shell' });
+    if (verified.unavailable) {
+      log('failed', 'failed', verified.detail);
+      return { outcome: 'failed', line, reason: verified.detail };
+    }
+    if (exitCode !== '0') {
+      const reason = `install exited ${exitCode}: ${screenTail(snapshot)}`;
+      log('failed', 'failed', reason);
+      return { outcome: 'failed', line, reason, ...(tool === 'codex' ? { needsLogin: true } : {}) };
+    }
+    if (verified.ok) {
+      log('installed', 'installed', verified.detail);
+      return codexLogin('installed', verified.detail, line);
+    }
+    const reason = screenTail(snapshot);
+    log('failed', 'failed', `${verified.detail} · ${reason}`);
+    return { outcome: 'failed', line, reason, ...(tool === 'codex' ? { needsLogin: true } : {}) };
+  } catch (error) {
+    const reason = `${error instanceof Error ? error.message : String(error)}${snapshot ? ` · ${screenTail(snapshot)}` : ''}`;
+    log('failed', 'failed', reason);
+    return { outcome: 'failed', line, reason, ...(tool === 'codex' ? { needsLogin: true } : {}) };
+  }
+}

package/src/agent-mission/tool-ladder.ts

@@ -0,0 +1,37 @@
+import type { EnvProfile } from './env-profile.js';
+
+export interface RungChoice {
+  rung: 1 | 2 | 3 | 4 | 5;
+  tool: string | null;
+  install: string[];
+  reason: string;
+}
+
+/** Selects a display-only starting rung; installation and execution belong to separate commands. */
+export function chooseRung(mission: string, profile: EnvProfile): RungChoice {
+  if (!mission.trim()) throw new Error('mission must not be empty');
+  const has = (tool: string) => profile.tools.includes(tool);
+  const choose = (rung: RungChoice['rung'], tool: string | null, reason: string): RungChoice => ({
+    rung, tool, install: tool !== null && !has(tool) ? [tool] : [], reason,
+  });
+
+  if (/리팩터|refactor|다른 눈|second (?:opinion|review)|large|대규모/i.test(mission)) {
+    return choose(5, 'codex', '큰 구현 또는 독립 리뷰에는 외부 코딩 에이전트');
+  }
+  if (/코드|수정|추가|구현|테스트|시험|bug|fix|implement|code|test/i.test(mission)) {
+    return choose(4, null, '코드 변경과 검증에는 Elanous 하니스');
+  }
+  if (/\b(?:csv|json|text|convert|transform)\b|변환|합계/i.test(mission)) {
+    return choose(1, /\bjson\b|JSON|csv|CSV/i.test(mission) ? 'jq' : 'awk', '텍스트 변환은 셸 도구로 시작');
+  }
+  if (/\b(?:video|gif|audio|ffmpeg)\b|영상|동영상|음성/i.test(mission)) {
+    return choose(1, 'ffmpeg', '미디어 변환은 셸 도구로 시작');
+  }
+  if (/\b(?:pull request|PR|draft|github)\b|깃허브|풀리퀘스트/i.test(mission)) {
+    return choose(2, 'gh', 'GitHub 조회는 도메인 CLI로 시작');
+  }
+  if (/로그|logs?|memory|기억/i.test(mission)) {
+    return choose(3, null, 'Elanous 관측·기억 능력으로 시작');
+  }
+  return choose(3, null, '명확한 하위 도구가 없어 Elanous 능력에서 시작 (실행 전 확인 필요)');
+}