elanous 0.2.42 → 0.2.43

package/src/cli/task-plugin-wizard-host.ts

@@ -0,0 +1,114 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { startClassicMissionCli } from '../dashboard/mission-cli-consumer.js';
+import type { MissionCliConsumerDeps } from '../dashboard/mission-cli-consumer.js';
+import { requestQuestion, getDefaultQuestionChannels } from '../hitl/question.js';
+import type { QuestionChannel } from '../hitl/question.js';
+import { sendOutbound } from '../domains/outbound-alert.js';
+import type { AskUserQuestionRequest, AskUserQuestionResult } from '../ask-user-question/types.js';
+import { PLUGIN_WIZARD_MARKET_QUESTION } from '../graph-wizard/mission-compose.js';
+import type { PluginMaker, PluginWizardDeps } from '../graph-wizard/mission-compose.js';
+
+export interface TaskPluginWizardHostResult {
+  ok: boolean;
+  content?: string;
+  error?: string;
+}
+
+export interface TaskPluginWizardHostPorts {
+  questionChannels?: () => QuestionChannel[];
+  sendReport?: (report: string, kind: 'report') => Promise<unknown> | unknown;
+  searchMarket?: PluginWizardDeps['searchMarket'];
+  missionConsumerDeps?: MissionCliConsumerDeps;
+  runMission?: (request: { maker: PluginMaker; prompt: string }) => Promise<TaskPluginWizardHostResult>;
+  runMissionPair?: (request: { makers: readonly PluginMaker[]; prompt: string }) => Promise<Partial<Record<PluginMaker, TaskPluginWizardHostResult>>>;
+  onEvent?: PluginWizardDeps['onEvent'];
+}
+
+async function runClassicMission(maker: PluginMaker, prompt: string, deps?: MissionCliConsumerDeps): Promise<TaskPluginWizardHostResult> {
+  const started = await startClassicMissionCli({ agent: maker, prompt }, deps);
+  const result = 'completion' in started ? await started.completion : started;
+  return { ok: result.ok, ...(result.content ? { content: result.content } : {}), ...(result.error ? { error: result.error } : {}) };
+}
+
+function questionRequest(questions: readonly string[]): AskUserQuestionRequest {
+  return {
+    questions: questions.map((question, index) => ({
+      id: `plugin_wizard_${index + 1}`,
+      header: '플러그인',
+      question,
+      options: question.trim() === PLUGIN_WIZARD_MARKET_QUESTION
+        ? [
+          { label: '마켓', description: '신뢰된 마켓 후보를 먼저 찾아 시험합니다.' },
+          { label: '사이드탭', description: 'Claude와 Codex에 같은 작업을 맡겨 비교합니다.' },
+        ]
+        : [
+          { label: '기본안', description: '마법사가 미션과 도구 이름에서 기본 구현을 정합니다.' },
+          { label: '직접 입력', description: '원하는 기능을 직접 적습니다.' },
+        ],
+      includeOther: true,
+    })),
+  };
+}
+
+function answerMap(result: AskUserQuestionResult): Record<string, string> | undefined {
+  const answers: Record<string, string> = {};
+  for (const [id, raw] of Object.entries(result.answers)) {
+    const typed = result.otherText?.[id]?.trim();
+    const value = typed || (Array.isArray(raw) ? raw.join(', ') : raw);
+    if (typeof value === 'string' && value.trim()) answers[id] = value.trim();
+  }
+  return Object.keys(answers).length ? answers : undefined;
+}
+
+async function pluginSpec(content: string | undefined, workspace: string): Promise<string> {
+  const spec = content?.match(/(?:^|\r?\n)PLUGIN_SPEC=([^\r\n]+)\s*$/m)?.[1]?.trim();
+  if (!spec || !isAbsolute(spec)) throw new Error('Claude/Codex 결과에 절대경로 PLUGIN_SPEC이 없습니다');
+  const [workspacePath, pluginPath] = await Promise.all([realpath(resolve(workspace)), realpath(resolve(spec))]);
+  const fromWorkspace = relative(workspacePath, pluginPath);
+  if (!fromWorkspace || fromWorkspace === '..' || fromWorkspace.startsWith(`..${sep}`) || isAbsolute(fromWorkspace)) {
+    throw new Error('Claude/Codex PLUGIN_SPEC은 세션 작업실 안의 경로여야 합니다');
+  }
+  return pluginPath;
+}
+
+/** Wire the plugin wizard onto existing question, outbound, and classic side-tab host abstractions. */
+export function createTaskPluginWizardHostDeps(ports: TaskPluginWizardHostPorts = {}): PluginWizardDeps {
+  const ask = async (request: AskUserQuestionRequest): Promise<AskUserQuestionResult> => {
+    const response = await requestQuestion({ request, channels: ports.questionChannels?.() ?? getDefaultQuestionChannels() });
+    return response.result;
+  };
+  const sendReport = ports.sendReport ?? ((report: string, kind: 'report') => sendOutbound(report, kind));
+  const runMission = ports.runMission ?? ((request: { maker: PluginMaker; prompt: string }) =>
+    runClassicMission(request.maker, request.prompt, ports.missionConsumerDeps));
+
+  return {
+    ask: async (questions) => answerMap(await ask(questionRequest(questions))),
+    // When omitted, composePluginMission uses its built-in trusted-market search.
+    ...(ports.searchMarket ? { searchMarket: ports.searchMarket } : {}),
+    develop: async ({ maker, goal, workspace }) => {
+      const prompt = [goal, '', `세션 작업실: ${workspace}`,
+        '플러그인을 작업실 안에 만들고, 끝에 PLUGIN_SPEC=<absolute plugin directory> 한 줄을 정확히 출력해 주세요.'].join('\n');
+      const result = await runMission({ maker, prompt });
+      if (!result.ok) throw new Error(result.error ?? `${maker} side-tab mission failed`);
+      return { spec: await pluginSpec(result.content, workspace) };
+    },
+    ...(ports.runMissionPair ? {
+      developPair: async ({ makers, goal, workspace }: { makers: readonly PluginMaker[]; goal: string; workspace: string }) => {
+        const prompt = [goal, '', `세션 작업실: ${workspace}`,
+          '플러그인을 작업실 안에 만들고, 끝에 PLUGIN_SPEC=<absolute plugin directory> 한 줄을 정확히 출력해 주세요.'].join('\n');
+        const results = await ports.runMissionPair!({ makers, prompt });
+        const specs: Partial<Record<PluginMaker, { spec: string }>> = {};
+        for (const maker of makers) {
+          const result = results[maker];
+          if (!result?.ok) continue;
+          try { specs[maker] = { spec: await pluginSpec(result.content, workspace) }; }
+          catch { /* one malformed maker result must not discard the other maker's candidate */ }
+        }
+        return specs;
+      },
+    } : {}),
+    notify: async (report) => { await sendReport(report, 'report'); },
+    ...(ports.onEvent ? { onEvent: ports.onEvent } : {}),
+  };
+}

package/src/cli/tasks-cli.ts

@@ -23,13 +23,16 @@ import { mapInventory, renderMapReduceTable, type MapInventory, type MapItem, ty
 import type { MapRecipe, MapRunRow } from '../task-agent/map-run-ledger.js';
 import { createMapHostLauncher, type HostMapItem } from '../task-agent/map-host-adapter.js';
 import type { GraphRunOptions, GraphRunState } from '../graph-runner/runner.js';
+import type { PluginWizardDeps } from '../graph-wizard/mission-compose.js';
+import type { TaskPluginWizardHostPorts } from './task-plugin-wizard-host.js';
 import { parseAskTargetPathHintsResult } from '../self-dev/launch-preflight-text.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
+import type { LaunchRequestDoor } from '../execution-loop/launch-gate.js';
 import { HAND_MOVE_KINDS, recordHandMove } from '../task-agent/live-move-history.js';
 import type { TierSizedDecompose } from '../task-agent/tier-split.js';
 import type { AdvanceMissionResult, MissionDecompose, PieceEvidenceReader } from '../task-agent/mission.js';
 import { formatSevenVerbLive, formatTaskAgentCover, measureSevenVerbLive, measureTaskAgentCover, type CoverRow, type ImplementCardRunBinding, type ImplementRunMergeEvent, type SevenVerbLive, type TaskAgentCoverInput } from '../task-agent/cover.js';
-import { measureRepairOutcomes } from '../task-agent/repair-outcomes.js';
+import { measureRepairOutcomes, measureRepairTierModels } from '../task-agent/repair-outcomes.js';
 import { LogStore, STORE_SAFETY_MAX, type LogQuery, type LogStoreRow } from '../mss/logging/log-store.js';
 import { resolveLogTargets } from './logs-cli.js';
 import { createTasksCliContext, handleError, NEXUS_DOWN, NexusUnavailable, registerTaskAgentSink, registerTaskListCommand, registerTaskShowCommand, registerTasksRoot, request, responseJson, TASK_AGENT_SINK_SURFACE } from './tasks-read-cli.js';
@@ -66,6 +69,18 @@ export interface TasksCliDeps {
   taskStatePath?: string;
   /** 조합 선택 시험에서만 그래프 저장소 루트를 바꾼다. */
   taskCompositionRoot?: string;
+  /** Isolated task hand launch-door injection; production uses the hand's instance-scoped default. */
+  taskLaunchRequestDoor?: LaunchRequestDoor;
+  /** Optional task-hand smart-plugin host bridge; production defaults use shared question/outbound and side-tab adapters. */
+  taskPluginWizardDeps?: PluginWizardDeps;
+  /** Test-only fake host ports; only consumed by `tasks hand --missing-tool`. */
+  taskPluginWizardHostPorts?: TaskPluginWizardHostPorts;
+  /** Graph-composition LLM seam for isolated `tasks hand --missing-tool` tests. */
+  taskComposeCallLLM?: import('../graph-wizard/generate.js').GraphWizardDeps['callLLM'];
+  /** Isolated plugin install root for the task-hand wizard. */
+  taskPluginInstallRoot?: string;
+  /** Isolated plugin marketplace directory for a task-hand wizard invocation. */
+  taskPluginMarketDir?: string;
   /** COORD-ENTRANCE-FOLD test seam; production uses the invoking repository root. */
   coordinatorShadowRoot?: string;
   /** Deterministic task-hand time in isolated tests. */
@@ -1973,9 +1988,20 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
         if (!existsSync(path)) throw new Error('TA 카드 원장 없음 — 수리 0건으로 판정 불가');
         const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(path).tasks;
         if (!tasks || typeof tasks !== 'object' || Array.isArray(tasks)) throw new Error('TA 카드 원장 tasks 없음 — 수리 0건으로 판정 불가');
-        const report = measureRepairOutcomes(Object.values(tasks), { since, until });
-        if (opts.json) out(JSON.stringify(report));
-        else out(`수리 결과(카드 원장) ${report.applied} 적용 · ${report.failed} 실패 · ${report.unconfirmed} 미확정 · 카드 ${report.cards} · 결과 ${report.results} · runId 결손 ${report.missingRunId} · 미지 효과 ${report.unknownEffect} (기간 내 최신 결과 · 판단 로그 아님)`);
+        const cards = Object.values(tasks);
+        const window = { since, until };
+        const report = measureRepairOutcomes(cards, window);
+        const tierModel = measureRepairTierModels(cards, window);
+        if (opts.json) out(JSON.stringify({ ...report,
+          window: { since: new Date(since).toISOString(), until: new Date(until).toISOString() }, tierModel,
+        }));
+        else {
+          out(`수리 결과(카드 원장) ${report.applied} 적용 · ${report.failed} 실패 · ${report.unconfirmed} 미확정 · 카드 ${report.cards} · 결과 ${report.results} · runId 결손 ${report.missingRunId} · 미지 효과 ${report.unknownEffect} (기간 내 최신 결과 · 판단 로그 아님)`);
+          out(`수리 호출 창 ${new Date(since).toISOString()} ≤ at < ${new Date(until).toISOString()} · 시도 ${tierModel.samples} · ${tierModel.measured ? '측정' : '미측정'}`);
+          for (const cell of tierModel.byTierModel) out(`${cell.tier}\t${cell.model}\t${cell.measured ? cell.n : '미측정'}`);
+          out(`Sol 호출 증거 ${tierModel.solCalls.length} · 호출 여부 미측정 ${tierModel.solCallUnmeasured.length}`);
+          for (const call of tierModel.solCalls) out(`Sol\t${call.tier}\t${call.card}\t${call.runId}\t${call.at}`);
+        }
       } catch (error) { out(error instanceof Error ? error.message : '수리 결과 원장 읽기 실패'); process.exitCode = 1; }
     });
 
@@ -2147,6 +2173,8 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
     .option('--goal <id>', '보드 소속 목표 id (task board)')
     .option('--milestone <id>', '보드 소속 이정표 id (task board)')
     .option('--target <dir>', '프로젝트 대상 디렉터리(있어야 한다 · 상대 경로는 절대로 · git 이 아니면 --completion 이 code-pr 밖이어야 한다) — 발사기를 이 디렉터리에서 띄운다')
+    .option('--missing-tool <capability>', '능동 비서가 감지한 빠진 도구 — 마켓/스마트 플러그인 마법사를 같은 task-hand 조합 경로에서 실행')
+    .option('--plugin-market-dir <dir>', '스마트 플러그인 마법사가 읽을 신뢰 마켓 인덱스 디렉터리')
     .option('--live', '실제로 발사한다(기본은 shadow — 명령만 출력)')
     .option('--ta-land', 'TA-LIVE-LAND-2 — 호스트는 재게이트만 하고 병합은 TASK-AGENT 의 propose-land(`pr land --expected-head`)에 맡긴다 · 카드 taLand ⊕ 발사 env ELANOUS_TA_LAND=1 · taskAgent.liveMoves 에 propose-land 가 없으면 종전대로 호스트가 병합')
     .option('--child-llm <provider/model>', 'TASKS-HAND-CHILD-LLM — 구현 자식 LLM(예: grok/grok-4.7) → 발사 인자 --child-llm-provider <provider> --child-llm-model <model> · «첫» `/` 에서만 가른다(모델 id 의 `/` 는 보존) · openrouter 는 모델 id 가 openrouter/ 접두를 포함하므로 전체를 모델로(openrouter/z-ai/glm-5.3 → --child-llm-model openrouter/z-ai/glm-5.3) · 카드 childLlm · 안 주면 명령·카드 무변경')
@@ -2156,7 +2184,7 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
     .option('--tag <k=v>', 'RUN-IDENTITY-TAGS — 출생 신분을 덮는다(class|care|rights|protect 의 k=v · 반복: --tag class=gate --tag protect=true) — 카드 원장 identity 에 남는다', (value: string, previous: string[] | undefined) => [...(previous ?? []), value])
     .option('--draft-claim <pr>', 'DRAFT-CLAIM-AUTO-2-FU — PR 를 관측(gh pr view)해 draftClaim 을 조립해 넘긴다 · 관측한 PR 머리에서 `elanous self review <pr> --json` 로 손 수확을 먼저 확정한다(확정 못 하면 claim 문면을 만들지 않는다) · claim 문면을 실제 PR 댓글로 게시(gh pr comment)한다 · 같은 PR 의 살아 있는 claim 기록(카드 draftClaim)이 있으면 거부한다')
     .option('--json', 'JSON 출력')
-    .action(async (text: string | undefined, opts: { seat?: TaskSeat; checklist?: string; version?: string; completion?: CompletionKind; mission?: string; project?: string; target?: string; goal?: string; milestone?: string; live?: boolean; taLand?: boolean; childLlm?: string; childLlmEffort?: string; roleLlm?: string[]; tier?: TaskCard['tier']; tag?: string[]; draftClaim?: string; json?: boolean }) => {
+    .action(async (text: string | undefined, opts: { seat?: TaskSeat; checklist?: string; version?: string; completion?: CompletionKind; mission?: string; project?: string; target?: string; missingTool?: string; pluginMarketDir?: string; goal?: string; milestone?: string; live?: boolean; taLand?: boolean; childLlm?: string; childLlmEffort?: string; roleLlm?: string[]; tier?: TaskCard['tier']; tag?: string[]; draftClaim?: string; json?: boolean }) => {
       const suppliedText = text !== undefined;
       /** RUN-IDENTITY-TAGS — 칸을 찾은 판(출생 신분이 그 판의 칸 우선순위를 읽는다 · 개발 판 밖 칸도). */
       let birthBoardVersion: string | undefined;
@@ -2291,13 +2319,17 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
           if (!repo) throw new Error(`현재 worktree origin이 GitHub 저장소가 아니다: ${origin}`);
           const run = deps.handOpenPrRun ?? ((command: string, args: string[]) => spawnSync(command, args,
             { cwd: process.cwd(), encoding: 'utf8', timeout: 20_000, maxBuffer: 16 * 1024 * 1024 }));
-          const listed = run('gh', ['pr', 'list', '--repo', repo, '--state', 'open', '--limit', '500', '--json', 'number,body']);
+          if (!/^[A-Z][A-Z0-9-]{2,}$/.test(opts.checklist)) throw new Error(`체크리스트 칸 ID 형식이 잘못됐다 — 구현 발사 0: ${opts.checklist}`);
+          const search = `in:body "${opts.checklist}"`;
+          const searchLimit = 1000;
+          const listed = run('gh', ['pr', 'list', '--repo', repo, '--state', 'open', '--search', search,
+            '--limit', String(searchLimit), '--json', 'number,body']);
           if (listed.status !== 0) throw new Error(`같은 칸 OPEN PR 조회 실패 — 구현 발사 0: ${opts.checklist}`);
           let rows: unknown;
           try { rows = JSON.parse(listed.stdout); } catch { throw new Error(`OPEN PR 목록 해석 실패 — 구현 발사 0: ${opts.checklist}`); }
-          if (!Array.isArray(rows) || rows.length >= 500 || !rows.every((row) =>
+          if (!Array.isArray(rows) || rows.length >= searchLimit || !rows.every((row) =>
             Number.isSafeInteger(doctorObject(row)?.number) && typeof doctorObject(row)?.body === 'string')) {
-            throw new Error(`OPEN PR 목록 불완전 — 구현 발사 0: ${opts.checklist}`);
+            throw new Error(`칸 ID 검색 결과 불완전 또는 ${searchLimit}건 상한 — 구현 발사 0: ${opts.checklist}`);
           }
           const openPrs = rows.filter((row) => cellIdFromBody(doctorObject(row)!.body as string) === opts.checklist)
             .map((row) => doctorObject(row)!.number as number);
@@ -2338,6 +2370,9 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
             return;
           }
         }
+        const pluginWizardDeps = opts.missingTool
+          ? deps.taskPluginWizardDeps ?? (await import('./task-plugin-wizard-host.js')).createTaskPluginWizardHostDeps(deps.taskPluginWizardHostPorts)
+          : undefined;
         const handOpts = {
           text: resolved.text,
           ...(resolved.kind === 'work-order' ? { workOrder: resolved.order } : {}),
@@ -2357,9 +2392,18 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
           ...(opts.roleLlm?.length ? { parentRoleLlm: opts.roleLlm } : {}),
           ...(opts.tier !== undefined ? { tier: opts.tier } : {}),
           ...(opts.tag !== undefined ? { tags: opts.tag } : {}),
+          ...(opts.missingTool && deps.taskComposeCallLLM ? { composeCallLLM: deps.taskComposeCallLLM } : {}),
           ...(birthBoardVersion !== undefined ? { checklistVersion: birthBoardVersion } : {}),
           ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}),
           ...(deps.taskCompositionRoot ? { compositionRoot: deps.taskCompositionRoot } : {}),
+          ...(deps.taskLaunchRequestDoor ? { launchRequestDoor: deps.taskLaunchRequestDoor } : {}),
+          ...(opts.missingTool ? { pluginWizard: {
+            missing: opts.missingTool,
+            root: deps.taskPluginInstallRoot ?? effectiveInstanceRoot(),
+            workspace: opts.target ? resolve(opts.target) : process.cwd(),
+            ...(opts.pluginMarketDir ?? deps.taskPluginMarketDir
+              ? { marketDir: resolve(opts.pluginMarketDir ?? deps.taskPluginMarketDir!) } : {}),
+          }, ...(pluginWizardDeps ? { pluginWizardDeps } : {}) } : {}),
           launcher: deps.taskLauncher ?? defaultTaskLauncher,
         };
         // DRAFT-CLAIM-AUTO-2-FU — 생산 배선: `--draft-claim <pr>` 로 관측·게시·수확 리뷰 포트를 끼워 draftClaim(⊕ 손 수확)을
@@ -2405,7 +2449,8 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
           if (result.cwd) out(`(cwd: ${result.cwd})`);
           if (result.card.taLand) out('(ta-land — 발사 env ELANOUS_TA_LAND=1 · 원격 또는 로컬 부모 · taskAgent.liveMoves 에 propose-land 가 있으면 병합은 TASK-AGENT 몫, 없으면 종전대로 호스트 병합)');
           if (!result.launched && result.card.alreadyDoneCandidate) out('(main 증거 통과 — 발사 0 · green 후보만 기록, 주인 판정 대기)');
-          else if (!result.launched) out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+          else if (!result.launched && result.mode === 'shadow') out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+          else if (!result.launched) out(`(발사되지 않음 — ${result.reason ?? result.move.reason})`);
         }
       } catch (error) {
         out(error instanceof Error ? error.message : '과제 넘기기 실패');

package/src/cli/tui-test-cli.ts

@@ -0,0 +1,186 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync, type ChildProcess } from 'node:child_process';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { spawnElanous } from '../instance/spawn-elanous.js';
+import { DEFAULT_TUI_TEST_READY_TIMEOUT_MS } from '../self-implement/elanous-tui-spawn.js';
+
+export interface TuiTestRunResult {
+  readonly worktree: string;
+  readonly ptyId: string;
+  readonly runId: string;
+  readonly nexusUrl: string;
+  readonly nexusPid: number;
+  readonly snapshotPath: string;
+  readonly readyTimeoutMs: number;
+  readonly waitedMs: number;
+  readonly pwaBuild: 'built' | 'reused' | 'skipped';
+}
+
+export interface TuiTestDeps {
+  readonly repoRoot?: string;
+  readonly now?: () => Date;
+  readonly run?: (command: string, args: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, timeoutMs?: number) => { status: number | null; stdout: string; stderr: string; error?: Error };
+  readonly fetch?: typeof fetch;
+}
+
+const runSync = (command: string, args: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, timeoutMs = 5 * 60_000) => {
+  const result = spawnSync(command, [...args], { cwd, env, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '', ...(result.error ? { error: result.error } : {}) };
+};
+
+export function pwaBuildRequired(pwaDir: string): boolean {
+  return !existsSync(join(pwaDir, 'out', 'index.html'));
+}
+
+export function pwaBuildDecision(pwaDir: string, withPwaBuild = false): 'build' | 'reuse' | 'skip' {
+  if (!pwaBuildRequired(pwaDir)) return 'reuse';
+  return withPwaBuild ? 'build' : 'skip';
+}
+
+export function buildHeldTuiArgs(entry: string, tuiStateDir: string, readyTimeoutMs: number, cwd: string): string[] {
+  return [entry, '--test', 'dev', '--elanous', '--hold', '--json', '--isolated-root', tuiStateDir, '--ready-timeout-ms', String(readyTimeoutMs), '--cwd', cwd];
+}
+
+export function parseReadyHeldPty(output: string): { id: string; runId: string } | undefined {
+  const rows = JSON.parse(output) as Array<{ id: string; runId?: string; alive: boolean }>;
+  const row = rows.find((item) => item.alive && !!item.runId);
+  return row?.runId ? { id: row.id, runId: row.runId } : undefined;
+}
+
+function checkedRun(deps: TuiTestDeps, command: string, args: readonly string[], cwd: string, env?: NodeJS.ProcessEnv, timeoutMs?: number): string {
+  const result = (deps.run ?? runSync)(command, args, cwd, env, timeoutMs);
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} failed (status=${result.status}): ${(result.stderr || result.stdout || result.error?.message || 'no diagnostic').trim()}`);
+  return result.stdout;
+}
+
+async function waitForNexus(logPath: string, child: ChildProcess, deadline: number, fetcher: typeof fetch): Promise<string> {
+  let last = 'no response';
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) throw new Error(`isolated Nexus exited before readiness (status=${child.exitCode}): ${readFileSync(logPath, 'utf8').slice(-1200)}`);
+    const log = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+    const port = /(?:http:\/\/(?:0\.0\.0\.0|127\.0\.0\.1):|시험 대역에서 :)([0-9]+)(?: 임대)?/u.exec(log)?.[1];
+    if (port) {
+      try {
+        const response = await fetcher(`http://127.0.0.1:${port}/v1/terminals`, { signal: AbortSignal.timeout(2_000) });
+        if (response.status < 500) return `http://127.0.0.1:${port}`;
+        last = `HTTP ${response.status}`;
+      } catch (error) { last = error instanceof Error ? error.message : String(error); }
+    } else if (log) last = log.slice(-500);
+    await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+  }
+  throw new Error(`isolated Nexus did not answer before the shared readiness deadline (${last})`);
+}
+
+function launchHeldTui(entry: string, cwd: string, env: NodeJS.ProcessEnv, stateDir: string, deadline: number): ChildProcess {
+  const logPath = join(stateDir, 'tui-test-held.log');
+  const logFd = openSync(logPath, 'a', 0o600);
+  let child: ChildProcess;
+  try {
+    child = spawnElanous(buildHeldTuiArgs(entry, join(stateDir, '..', '.elanous-test-tui'), Math.max(1, deadline - Date.now()), cwd).slice(1), {
+      bin: entry,
+      stateDir: join(stateDir, '..', '.elanous-test-tui'),
+      cwd, env, detached: true, stdio: ['ignore', logFd, logFd],
+    });
+  } finally {
+    closeSync(logFd);
+  }
+  child.unref();
+  child.once('error', () => {});
+  return child;
+}
+
+async function waitForHeldTui(entry: string, cwd: string, env: NodeJS.ProcessEnv, stateDir: string, child: ChildProcess, deadline: number, deps: TuiTestDeps): Promise<{ id: string; runId: string }> {
+  const logPath = join(stateDir, 'tui-test-held.log');
+  const startedAt = Date.now();
+  let last = 'PTY registry has no row yet';
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      const output = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+      throw new Error(`held TUI launcher exited before its PTY was registered (status=${child.exitCode}): ${output.slice(-1200)}`);
+    }
+    try {
+      const output = checkedRun(deps, 'bun', [entry, '--test-state-dir', stateDir, 'pty', 'list', '--json'], cwd, env, Math.min(15_000, Math.max(1, deadline - Date.now())));
+      const held = parseReadyHeldPty(output);
+      if (held) return held;
+      last = 'PTY registry returned no alive held TUI';
+    } catch (error) {
+      last = error instanceof Error ? error.message : String(error);
+    }
+    await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));
+  }
+  if (child.pid !== undefined) {
+    try { process.kill(-child.pid, 'SIGTERM'); } catch { /* process may already have exited */ }
+  }
+  const output = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+  throw new Error(`held TUI did not register an alive PTY before the shared deadline (waitedMs=${Date.now() - startedAt}; ${last}): ${output.slice(-1200)}`);
+}
+
+export async function runTuiTestUniverse(options: { readyTimeoutMs?: number; withPwaBuild?: boolean } = {}, deps: TuiTestDeps = {}): Promise<TuiTestRunResult> {
+  const repoRoot = resolve(deps.repoRoot ?? process.cwd());
+  const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_TUI_TEST_READY_TIMEOUT_MS;
+  if (!Number.isSafeInteger(readyTimeoutMs) || readyTimeoutMs < 1) throw new Error('--ready-timeout-ms must be a positive integer');
+  const stamp = (deps.now ?? (() => new Date()))().toISOString().replace(/[-:.]/gu, '').replace('T', '-').replace('Z', 'Z');
+  const branch = `codex/tui-test-${stamp}`;
+  const worktreeBase = join(getElanousConfigDir(), 'worktrees', 'tui-test');
+  const worktree = join(worktreeBase, stamp);
+  mkdirSync(worktreeBase, { recursive: true });
+
+  checkedRun(deps, 'git', ['fetch', 'origin', 'main'], repoRoot, undefined, 60_000);
+  checkedRun(deps, 'git', ['worktree', 'add', '-b', branch, worktree, 'origin/main'], repoRoot, undefined, 5 * 60_000);
+  const { linkWorktreeDependencies } = await import('../git-fs/worktree.js');
+  linkWorktreeDependencies(repoRoot, worktree, ['node_modules']);
+
+  const pwaDir = join(worktree, 'apps/pwa');
+  const pwaDecision = pwaBuildDecision(pwaDir, options.withPwaBuild);
+  let pwaBuild: TuiTestRunResult['pwaBuild'] = pwaDecision === 'reuse' ? 'reused' : 'skipped';
+  if (pwaDecision === 'build') {
+    checkedRun(deps, 'bun', ['install', '--frozen-lockfile'], pwaDir, undefined, 5 * 60_000);
+    checkedRun(deps, 'bun', ['run', 'build'], pwaDir, undefined, 10 * 60_000);
+    pwaBuild = 'built';
+  }
+
+  const entry = join(worktree, 'bin/elanous.mjs');
+  const testStateDir = join(worktree, '.elanous-test');
+  const tuiStateDir = join(worktree, '.elanous-test-tui');
+  const testEnv = { ...process.env };
+  delete testEnv.ELANOUS_STATE_DIR;
+  delete testEnv.ELANOUS_CONFIG_DIR;
+  delete testEnv.ELANOUS_NEXUS_HEADLESS;
+  checkedRun(deps, 'bun', [entry, 'config', 'sync-test', '--state-dir', testStateDir, '--json'], worktree, testEnv, 30_000);
+  checkedRun(deps, 'bun', [entry, '--config-dir', testStateDir, 'config', 'set', 'global.nexus.pwa.shareTailnet', 'disabled', '--no-backup'], worktree, testEnv, 30_000);
+  mkdirSync(testStateDir, { recursive: true });
+  const nexusLogPath = join(testStateDir, 'tui-test-nexus.log');
+  const nexusLogFd = openSync(nexusLogPath, 'a');
+  const nexusEntry = join(repoRoot, 'bin/elanous.mjs');
+  const nexusEnv = { ...testEnv, ELANOUS_CONFIG_DIR: testStateDir, ELANOUS_TOOL_CWD: worktree };
+  const nexusProcess = spawnElanous(['--test-state-dir', testStateDir, 'nexus', 'run', '--no-auto-build', '--no-watch', '--no-mcp', '--no-auth', '--http-host', '127.0.0.1', '--tool-cwd', worktree], {
+    bin: nexusEntry,
+    stateDir: testStateDir,
+    cwd: worktree, env: nexusEnv, detached: true, stdio: ['ignore', nexusLogFd, nexusLogFd],
+  });
+  closeSync(nexusLogFd);
+  nexusProcess.unref();
+  const readinessDeadline = Date.now() + readyTimeoutMs;
+  try {
+    const nexusUrl = await waitForNexus(nexusLogPath, nexusProcess, readinessDeadline, deps.fetch ?? fetch);
+    const ptyReadyStartedAt = Date.now();
+    const launcher = launchHeldTui(entry, worktree, testEnv, testStateDir, readinessDeadline);
+    const held = await waitForHeldTui(entry, worktree, testEnv, testStateDir, launcher, readinessDeadline, deps);
+    const ptyId = held.id;
+
+    const isolatedArgs = ['--test-state-dir', testStateDir];
+    const ptyList = JSON.parse(checkedRun(deps, 'bun', [entry, ...isolatedArgs, 'pty', 'list', '--json'], worktree, testEnv, 30_000)) as Array<{ id: string; runId?: string; alive: boolean }>;
+    const row = ptyList.find((item) => item.id === ptyId && item.alive);
+    if (row?.runId !== held.runId) throw new Error(`held PTY ${ptyId} is absent or has a different runId in the same test universe`);
+    const snapshot = checkedRun(deps, 'bun', [entry, ...isolatedArgs, 'pty', 'snapshot', ptyId], worktree, testEnv, 30_000);
+    const evidenceDir = join(testStateDir, 'evidence');
+    const snapshotPath = join(evidenceDir, 'tui-test-snapshot.txt');
+    mkdirSync(evidenceDir, { recursive: true });
+    writeFileSync(snapshotPath, snapshot, 'utf8');
+    return { worktree, ptyId, runId: row.runId, nexusUrl, nexusPid: nexusProcess.pid ?? -1, snapshotPath, readyTimeoutMs, waitedMs: Date.now() - ptyReadyStartedAt, pwaBuild };
+  } catch (error) {
+    try { checkedRun(deps, 'bun', [entry, '--test-state-dir', testStateDir, 'nexus', 'stop'], worktree, testEnv, 15_000); } catch { /* preserve the primary readiness failure */ }
+    throw error;
+  }
+}

package/src/config.ts

@@ -7,6 +7,7 @@ import { listSshHosts } from './ssh/ssh-hosts.js';
 import { isInstalledPackagePath } from './instance/installed-package.js';
 import { defaultObsidianVault } from './obsidian/default-vault.js';
 import { OPENGATEWAY_DEFAULT_MODEL } from './llm/opengateway-models.js';
+import { SERVICE_KEY_CATALOG } from './setup/service-key-catalog.js';
 
 // ── User config ──
 export const REMOTE_HOME = homedir();
@@ -191,10 +192,11 @@ export function refreshKeyFromCache(envName: string): boolean {
  * (음성 STT/TTS 등) plist 에서 키만 빼면 조용히 죽는다 ⇒ 부팅 한 곳에서 캐시를 env 에 싣는다(규약 = 캐시 우선 · ⓐⓑ 동일).
  * 자식 프로세스도 이 env 를 물려받는다. 반환 = 캐시로 채운 이름(값은 절대 안 싣는다).
  */
-export const DAEMON_KEY_ENV_NAMES = [
+export const DAEMON_KEY_ENV_NAMES = [...new Set([
   'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'XAI_API_KEY', 'OPENROUTER_API_KEY', 'OPENGATEWAY_API_KEY',
   'ELANOUS_OPENAI_RELAY_SHARED_SECRET',
-] as const;
+  ...SERVICE_KEY_CATALOG.flatMap(item => item.envNames),
+])];
 
 export function hydrateEnvFromKeyCache(names: readonly string[] = DAEMON_KEY_ENV_NAMES, env: NodeJS.ProcessEnv = process.env): string[] {
   const filled: string[] = [];