elanous 0.2.42 → 0.2.43

package/src/self-implement/runtime-overlay-run-steps.ts

@@ -0,0 +1,95 @@
+import type { GraphTemplate } from './graph-templates.js';
+import type { GraphTemplateSpec } from './graph-yaml.js';
+import type { RunLedgerEntry } from './run-ledger.js';
+
+type RuntimeOverlayGraph = Pick<GraphTemplate, 'nodes' | 'edges'> | Pick<GraphTemplateSpec, 'nodes' | 'edges'>;
+
+const DEFAULT_OUTCOME = '$default';
+const ABSENT_ROUTE = '$absent';
+
+export interface RuntimeOverlayRunStepsInput {
+  readonly runId: string;
+  readonly timestamp: string;
+  readonly before: RuntimeOverlayGraph;
+  readonly after: RuntimeOverlayGraph;
+  readonly overlayIds: readonly string[];
+  readonly round: number;
+}
+
+interface GraphRoute {
+  readonly from: string;
+  readonly outcome: string;
+  readonly to: string;
+}
+
+function routesOf(graph: RuntimeOverlayGraph): Map<string, GraphRoute> {
+  const routes = new Map<string, GraphRoute>();
+  if (!Array.isArray(graph.edges)) {
+    const compiledEdges = graph.edges as Readonly<Record<string, readonly string[]>>;
+    for (const [from, destinations] of Object.entries(compiledEdges)) {
+      for (const [index, to] of destinations.entries()) {
+        routes.set(`${from}\u0000${index}`, { from, outcome: String(index), to: String(to) });
+      }
+    }
+    return routes;
+  }
+  for (const edge of graph.edges) {
+    if (edge.to !== undefined) {
+      routes.set(`${edge.from}\u0000${DEFAULT_OUTCOME}`, { from: edge.from, outcome: DEFAULT_OUTCOME, to: edge.to });
+      continue;
+    }
+    for (const [outcome, to] of Object.entries(edge.map ?? {})) {
+      routes.set(`${edge.from}\u0000${outcome}`, { from: edge.from, outcome, to: String(to) });
+    }
+  }
+  return routes;
+}
+
+function reason(input: RuntimeOverlayRunStepsInput): string {
+  return `runtime overlay ${input.overlayIds.join(', ')} applied at round ${input.round}`;
+}
+
+/** Convert an already accepted runtime overlay into the existing structural ledger vocabulary. */
+export function runtimeOverlayRunSteps(input: RuntimeOverlayRunStepsInput): RunLedgerEntry[] {
+  if (input.overlayIds.length === 0) return [];
+  const detail = reason(input);
+  const beforeNodes = new Set(input.before.nodes.map((node) => node.nodeId));
+  const entries: RunLedgerEntry[] = input.after.nodes
+    .filter((node) => !beforeNodes.has(node.nodeId))
+    .map((node) => ({
+      timestamp: input.timestamp,
+      runId: input.runId,
+      event: 'node-added',
+      data: {
+        node: node.nodeId,
+        kind: node.kind,
+        decider: 'runtime-overlay',
+        reason: detail,
+        trigger: { overlayIds: input.overlayIds, round: input.round },
+      },
+    }));
+
+  const beforeRoutes = routesOf(input.before);
+  const afterRoutes = routesOf(input.after);
+  const changedRoutes = [...afterRoutes.entries()]
+    .filter(([key, route]) => beforeRoutes.get(key)?.to !== route.to)
+    .sort(([left], [right]) => left.localeCompare(right));
+  for (const [key, route] of changedRoutes) {
+    entries.push({
+      timestamp: input.timestamp,
+      runId: input.runId,
+      event: 'edge-rerouted',
+      data: {
+        from: route.from,
+        outcome: route.outcome,
+        to: route.to,
+        was: beforeRoutes.get(key)?.to ?? ABSENT_ROUTE,
+        decider: 'runtime-overlay',
+        reason: detail,
+      },
+    });
+  }
+  return entries;
+}
+
+export { ABSENT_ROUTE, DEFAULT_OUTCOME };

package/src/self-implement/tdd-evidence-tags.ts

@@ -0,0 +1,9 @@
+/** Stable TDD terminal-evidence tags shared by the producer and Pod result mapper. */
+export const TDD_RED_TAG = 'tdd-red' as const;
+export const TDD_GREEN_TAG = 'tdd-green' as const;
+export const TDD_RECORD_TAGS = [TDD_RED_TAG, TDD_GREEN_TAG] as const;
+export type TddRecordTag = typeof TDD_RECORD_TAGS[number];
+
+export function isTddRecordTag(value: unknown): value is TddRecordTag {
+  return value === TDD_RED_TAG || value === TDD_GREEN_TAG;
+}

package/src/self-implement/train-gate-receipt.ts

@@ -0,0 +1,166 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
+import {
+  computeReceiptKey,
+  gateEnvFingerprint,
+  gateLockfileHash,
+  GATE_RECEIPT_SCHEMA,
+  loadGateReceipts,
+  saveGateReceipt,
+  type GateReceipt,
+  type GateReceiptIdentity,
+} from './gate-receipt-registry.js';
+
+export interface TrainGateReceiptInput {
+  repo: string;
+  commit: string;
+  baseSha: string;
+  changedFiles: readonly string[];
+  deletedFiles?: readonly string[];
+  scenarioTests?: readonly string[];
+}
+
+export interface PassedSelfGateReceiptInput extends TrainGateReceiptInput {
+  /** Exact artifact emitted by `self gate --artifact-dir`; its pass and typecheck binding are revalidated here. */
+  summaryPath: string;
+}
+
+type Execute = (script: string, cwd: string) => { status: number | null; stdout: string; stderr: string };
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
+
+function registryPath(repo: string): string | undefined {
+  const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: repo, encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  const commonDir = (result.stdout ?? '').trim();
+  return result.status === 0 && commonDir ? join(commonDir, 'elanous-host-regate', 'gate-receipts.json') : undefined;
+}
+
+function identityFor(input: TrainGateReceiptInput, checks?: readonly string[]): GateReceiptIdentity | undefined {
+  if (!SHA40.test(input.commit) || !SHA40.test(input.baseSha)) return undefined;
+  const bun = spawnSync('bun', ['--version'], { cwd: input.repo, encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  const bunVersion = (bun.stdout ?? '').trim();
+  if (bun.status !== 0 || !bunVersion) return undefined;
+  return {
+    headCommit: input.commit,
+    baseCommit: input.baseSha,
+    bunVersion,
+    lockfileHash: gateLockfileHash(input.repo),
+    radiusFiles: [...new Set(input.changedFiles)].sort(),
+    checks: checks ? [...checks] : [
+      'train:changed-file-typecheck',
+      ...(input.scenarioTests?.length || input.changedFiles.some((file) => TEST_FILE.test(file) && !input.deletedFiles?.includes(file)) ? ['train:deterministic-tests'] : []),
+      ...(input.scenarioTests ?? []).map((file) => `train:scenario-test:${file}`),
+      'train:pwa-build',
+    ],
+    envFingerprint: gateEnvFingerprint(process.env),
+  };
+}
+
+/** Record only after revalidating the exact self-gate summary, then independently measure changed-only interference. */
+export async function recordPassedSelfGateReceipt(
+  input: PassedSelfGateReceiptInput,
+  detect: (files: readonly string[]) => Promise<{ status: 'no-interference' | 'interference' | 'unmeasurable' }> = async (files) => {
+    const { detectTestInterference } = await import('../../scripts/detect-test-interference.js');
+    return detectTestInterference(files);
+  },
+): Promise<GateReceipt | undefined> {
+  let summary: Record<string, unknown>;
+  try { summary = JSON.parse(readFileSync(input.summaryPath, 'utf8')) as Record<string, unknown>; }
+  catch { return undefined; }
+  const typecheck = summary.typecheck as Record<string, unknown> | undefined;
+  const cohort = Array.isArray(summary.cohort) ? summary.cohort.filter((file): file is string => typeof file === 'string') : [];
+  const changedTestFiles = [...new Set(input.changedFiles.filter((file) => TEST_FILE.test(file)
+    && !input.deletedFiles?.includes(file)))].sort();
+  if (summary.head40 !== input.commit || summary.base40 !== input.baseSha || summary.exitCode !== 0
+    || !['passed', 'pass'].includes(String(summary.verdict)) || summary.introduced !== 0
+    || summary.unknown !== 0 || summary.unrunImporters !== 0
+    || typecheck?.status !== 'passed' || typecheck.base40 !== input.baseSha
+    || typecheck.head40 !== input.commit || typecheck.exitCode !== 0 || typecheck.newErrors !== 0
+    || changedTestFiles.some((file) => !cohort.includes(file))) return undefined;
+  const testFiles = [...new Set(input.changedFiles.filter((file) => TEST_FILE.test(file)
+    && !input.deletedFiles?.includes(file)))].sort();
+  if (!testFiles.length) return undefined;
+  const interference = await detect(testFiles);
+  if (interference.status !== 'no-interference') return undefined;
+  const identity = identityFor(input, ['test-interference:changed-only']);
+  const path = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH || registryPath(input.repo);
+  if (!identity || !path) return undefined;
+  const receipt = passedEvidenceReceipt(identity, input.changedFiles);
+  try { saveGateReceipt(path, receipt); }
+  catch { return undefined; }
+  return receipt;
+}
+
+function scriptFor(input: TrainGateReceiptInput, files: readonly string[]): string {
+  const tests = [...new Set([
+    ...files.filter((file) => TEST_FILE.test(file) && !input.deletedFiles?.includes(file)),
+    ...(input.scenarioTests ?? []),
+  ])];
+  return [
+    `TSC_BASE_REF=${quote(input.baseSha)} bun scripts/ci-typecheck-changed.ts --local`,
+    ...(tests.length ? [`bun run test:deterministic ${tests.map(quote).join(' ')}`] : []),
+    `bun scripts/ci-pwa-build-gate.ts --changed-files ${files.map(quote).join(' ')}`,
+  ].join(' && ');
+}
+
+function passedEvidenceReceipt(identity: GateReceiptIdentity, files: readonly string[]): GateReceipt {
+  const receiptIdentity: GateReceiptIdentity = { ...identity, radiusFiles: [...new Set(files)].sort() };
+  return {
+    ...receiptIdentity,
+    schema: GATE_RECEIPT_SCHEMA,
+    key: computeReceiptKey(receiptIdentity, 'passed'),
+    verdict: 'passed',
+    savedAt: new Date().toISOString(),
+  };
+}
+
+export function runTrainGateWithReceipts(input: TrainGateReceiptInput, execute: Execute = (script, cwd) => {
+  const result = spawnSync('sh', ['-c', script], { cwd, encoding: 'utf8', timeout: 120 * 60_000, maxBuffer: 32 * 1024 * 1024 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}): { status: number | null; stdout: string; stderr: string } {
+  const context = identityFor(input);
+  const path = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH || registryPath(input.repo);
+  if (!context || !path) return execute(scriptFor(input, input.changedFiles), input.repo);
+
+  const changedFiles = [...new Set(input.changedFiles)].sort();
+  const result = execute(scriptFor(input, changedFiles), input.repo);
+  if (result.status === 0 && changedFiles.length) {
+    try { saveGateReceipt(path, passedEvidenceReceipt(context, changedFiles)); }
+    catch { /* A receipt is an optimization; a passed gate remains passed if persistence fails. */ }
+  }
+  return result;
+}
+
+if (import.meta.main) {
+  const raw = process.argv[2];
+  try {
+    if (!raw) throw new Error('train gate receipt input is required');
+    const input = JSON.parse(raw) as TrainGateReceiptInput & Partial<PassedSelfGateReceiptInput>;
+    if (input.summaryPath) {
+      const receipt = await recordPassedSelfGateReceipt(input as PassedSelfGateReceiptInput);
+      const registryFile = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH;
+      if (registryFile) {
+        const registry = loadGateReceipts(registryFile);
+        process.stdout.write(`${String.fromCharCode(10)}__GATE_RECEIPTS__${Buffer.from(JSON.stringify(registry)).toString('base64')}${String.fromCharCode(10)}`);
+      }
+      if (!receipt) process.exitCode = 1;
+    } else {
+      const result = runTrainGateWithReceipts({ ...input, repo: process.cwd() });
+      process.stdout.write(result.stdout);
+      process.stderr.write(result.stderr);
+      const registryFile = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH;
+      if (registryFile) {
+        const registry = loadGateReceipts(registryFile);
+        process.stdout.write(`${String.fromCharCode(10)}__GATE_RECEIPTS__${Buffer.from(JSON.stringify(registry)).toString('base64')}${String.fromCharCode(10)}`);
+      }
+      process.exitCode = result.status ?? 1;
+    }
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/self-implement/train-gate-remote.ts

@@ -3,8 +3,12 @@
  *  Unlike `dispatchHeavyCheck` it never falls back to a local run: a busy host or an infra failure is «unmeasured».
  *  The only local commands are git (cat-file · rev-parse · push · diff). */
 import { debug } from '../debug/log.js';
+import { spawnSync } from 'node:child_process';
 import { parseGateScenario, readGateScenarioFile } from './gate-scenario.js';
 import { getDefaultLogStore } from '../mss/logging/log-store.js';
+import { join } from 'node:path';
+import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
+import { saveGateReceipt, type GateReceipt } from './gate-receipt-registry.js';
 import {
   gateRemoteHostCap, realGateRemoteRunner, resolveGateRemoteSettings, runOnRemote,
   type GateRemoteRunner, type GateRemoteSettings, type RemoteRunOutcome,
@@ -30,6 +34,51 @@ export interface TrainGateInput {
 
 export interface TrainGateResult { outcome: TrainGateOutcome; host: string; ms?: number; rc?: number; reason?: string }
 
+const GATE_RECEIPTS_MARKER = String.fromCharCode(10) + '__GATE_RECEIPTS__';
+
+function sharedGateReceiptPath(repo: string, runner: GateRemoteRunner): string | undefined {
+  try {
+    const result = runner.local('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], repo);
+    const commonDir = result.stdout.trim();
+    return result.rc === 0 && commonDir ? join(commonDir, 'elanous-host-regate', 'gate-receipts.json') : undefined;
+  } catch { return undefined; }
+}
+
+/** The exact persistent registry used by local train receipt merging. */
+export function gateReceiptRegistryPathForRepo(repo: string): string | undefined {
+  const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    cwd: repo, encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER,
+  });
+  const commonDir = (result.stdout ?? '').trim();
+  return result.status === 0 && commonDir ? join(commonDir, 'elanous-host-regate', 'gate-receipts.json') : undefined;
+}
+
+/** Merge the existing remote-writer marker into the local common-dir registry. Invalid rows fail closed. */
+export function mergeGateReceiptRegistryPayload(payload: string, path: string): number {
+  let saved = 0;
+  try {
+    const rows = JSON.parse(Buffer.from(payload, 'base64').toString('utf8')) as Record<string, unknown>;
+    for (const [key, value] of Object.entries(rows)) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+      const receipt = value as GateReceipt;
+      if (receipt.key !== key) continue;
+      try { saveGateReceipt(path, receipt); saved++; }
+      catch { /* Invalid remote records are discarded; local gates remain fail-open. */ }
+    }
+  } catch { /* A malformed response never changes the measured gate verdict. */ }
+  return saved;
+}
+
+function mergeReturnedReceipts(outcome: RemoteRunOutcome, path: string | undefined): RemoteRunOutcome {
+  if (outcome.kind !== 'ran' || outcome.rc !== 0 || !path) return outcome;
+  const stdout = outcome.stdout.toString('utf8');
+  const marker = stdout.lastIndexOf(GATE_RECEIPTS_MARKER);
+  if (marker < 0) return outcome;
+  const payload = stdout.slice(marker + GATE_RECEIPTS_MARKER.length).trim();
+  mergeGateReceiptRegistryPayload(payload, path);
+  return { ...outcome, stdout: Buffer.from(stdout.slice(0, marker)) };
+}
+
 export interface TrainGateObservation {
   host: string; commit: string; baseSha: string; outcome: TrainGateOutcome;
   rc?: number; ms?: number; reason?: string; changedFiles: number;
@@ -42,22 +91,6 @@ export interface TrainGateDeps {
   observe?: (entry: TrainGateObservation) => void;
 }
 
-const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
-const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
-
-/** The host-side shell body: each step runs only if the one before it passed. Exported for tests. */
-export function trainGateScript(baseSha: string, changedFiles: readonly string[], deleted: ReadonlySet<string> = new Set(), scenarioTests: readonly string[] = []): string {
-  // A deleted test file is a changed path (tsc/PWA reach) but not something to run.
-  const changedTests = changedFiles.filter((file) => TEST_FILE.test(file) && !deleted.has(file));
-  const tests = scenarioTests.length ? [...new Set([...changedTests, ...scenarioTests])] : changedTests;
-  const steps = [
-    `TSC_BASE_REF=${quote(baseSha)} bun scripts/ci-typecheck-changed.ts --local`,
-    ...(tests.length ? [`bun run test:deterministic ${tests.map(quote).join(' ')}`] : []),
-    `bun scripts/ci-pwa-build-gate.ts --changed-files ${changedFiles.map(quote).join(' ')}`,
-  ];
-  return steps.join(' && ');
-}
-
 async function loadSettings(): Promise<GateRemoteSettings> {
   try {
     const { getUserConfig } = await import('../user-config.js');
@@ -76,6 +109,10 @@ export const TRAIN_GATE_HOST = 'node-b';
 
 export async function runTrainGateOnHost(input: TrainGateInput, runner: GateRemoteRunner = realGateRemoteRunner, deps: TrainGateDeps = {}): Promise<TrainGateResult> {
   const settings = input.settings ?? await loadSettings();
+  const receiptPath = sharedGateReceiptPath(input.repo, runner);
+  // Each remote full gate writes into a fresh scratch registry; returned rows merge into the local shared registry.
+  // No existing registry contents are needed for receipt registration.
+  const payloadFiles = receiptPath ? [{ env: 'ELANOUS_GATE_RECEIPT_REGISTRY_PATH', content: '{}' }] : undefined;
   const host = settings.host;
   const hostCap = gateRemoteHostCap(settings, host);
   let scenarioTests: string[] = [];
@@ -110,14 +147,21 @@ export async function runTrainGateOnHost(input: TrainGateInput, runner: GateRemo
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
   const now = deps.now ?? Date.now;
   const deadline = now() + settings.slotWaitSeconds * 1000;
-  const script = trainGateScript(input.baseSha, input.changedFiles, new Set(input.deletedFiles ?? []), scenarioTests);
   let outcome: RemoteRunOutcome;
   for (;;) {
     try {
       outcome = runOnRemote({
         repo: input.repo, host, mirror: settings.mirror, commit: input.commit, refs: [input.baseSha],
-        argv: ['sh', '-c', script], installPwa: true, hostCap,
+        argv: ['bun', 'src/self-implement/train-gate-receipt.ts', JSON.stringify({
+          repo: input.repo,
+          commit: input.commit,
+          baseSha: input.baseSha,
+          changedFiles: input.changedFiles,
+          deletedFiles: input.deletedFiles ?? [],
+          scenarioTests,
+        })], installPwa: true, hostCap, ...(payloadFiles ? { payloadFiles } : {}),
       }, runner);
+      outcome = mergeReturnedReceipts(outcome, receiptPath);
     } catch (error) {
       outcome = { kind: 'infra', reason: `exception: ${error instanceof Error ? error.message : String(error)}` };
     }

package/src/session/chat.ts

@@ -511,8 +511,9 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
     // streamLLMWithTools)으로 라우팅. 미아밍이면 아래 기존 single-turn 경로 그대로(회귀 0).
     const goalLoopCfg = opts.userConfig.llm.goalLoop;
     const armGoalLoop = opts.goalLoop === true || goalLoopCfg?.enabled === true;
-    const armTuiResearchTurn = opts.utteranceSurface === 'tui' && turnTools.length > 0 && isResearchAgentIntent(opts.userText);
-    if (armGoalLoop || armTuiResearchTurn) {
+    const armResearchTurn = (opts.utteranceSurface === 'tui' || opts.utteranceSurface === 'ask')
+      && turnTools.length > 0 && isResearchAgentIntent(opts.userText);
+    if (armGoalLoop || armResearchTurn) {
       // ⭐ CHILD-CONTEXT-BUDGET(0.2.35 칸) — 구현 자식(self-implement 공간)의 첫 goal-loop
       //    턴에서 실제 effectiveSystemPrompt·turnTools 스키마·userText(골)의 구성 바이트를
       //    composeChildContext 로 계측해 child.context-composition 사건 1회로 남긴다.
@@ -563,6 +564,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
           },
         },
         ...(turnLlmOpts?.model ? { modelOverride: turnLlmOpts.model } : {}),
+        ...(turnLlmOpts?.reasoningEffort ? { reasoningEffort: turnLlmOpts.reasoningEffort } : {}),
         ...(turnLlmOpts?.budgetGrant ? { budgetGrant: turnLlmOpts.budgetGrant } : {}),
         ...(guardedTurnLlmOpts?.requestSizeGuard
           ? { requestSizeGuard: guardedTurnLlmOpts.requestSizeGuard } : {}),

package/src/session/session-fanout.ts

@@ -224,6 +224,8 @@ export interface SessionChunkEvent {
   seq: number;
   /** 텍스트 델타(누적은 sink 의 라이브핸들이). */
   delta?: string;
+  /** Replace the current assistant text accumulated for this stream. */
+  textOperation?: 'replace';
   /** 툴 활동(⚙️…✓ inline 렌더용). */
   tool?: { id: string; name: string; phase: 'call' | 'result'; ok?: boolean };
   /** 🧠 추론(모드 gated·선택). */

package/src/session/streaming/acp-stream-sink.ts

@@ -36,7 +36,8 @@ export function createAcpStreamSink(broadcast: AcpBroadcast): StreamingSurfaceSi
       if (!sessionId) return;
       if (ev.delta) {
         // push(chunk) 등가 — agent_message_chunk(byte-identical).
-        void broadcast(sessionId, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: ev.delta } });
+        void broadcast(sessionId, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: ev.delta },
+          ...(ev.textOperation === 'replace' ? { _meta: { elanous: { textOperation: 'replace' } } } : {}) });
       }
       if (ev.reasoning) {
         // 🧠 추론 — agent_thought_chunk(ACP 의 thought 채널).

package/src/session/streaming/chunk-producer.ts

@@ -20,6 +20,7 @@ import { debug } from '../../debug/log.js';
  *  shadow 시엔 'acp' 구독자 부재 → tg/dc/pwa 미러만. reasoning 채널 추가 지원. */
 export interface AcpChunkProducer {
   delta: (text: string) => void;
+  replaceText: (text: string) => void;
   /** ⭐ `result` 는 «결과 단계»에서만 뜻이 있고, 주면 ACP `rawOutput` 으로 실려 나간다.
    *
    *  ⛔⭐⭐ **「안 줬다」의 «사유»를 여기서 만들지 않는다.**
@@ -53,6 +54,11 @@ export function makeAcpChunkProducer(sessionId: string, opts: { streamId?: strin
       fo({ streamId, seq: seq++, delta: text });
       deltas++;
     },
+    replaceText(text: string): void {
+      accum = text;
+      fo({ streamId, seq: seq++, delta: text, textOperation: 'replace' });
+      deltas++;
+    },
     tool(id, name, phase, ok, result): void {
       fo({ streamId, seq: seq++, tool: {
         id, name, phase,

package/src/session/streaming/stream-compositor.ts

@@ -46,9 +46,10 @@ export function createCompositorState(): CompositorState {
 /** 청크 이벤트를 상태에 반영(순수·in-place). delta/reasoning/tool 을 흡수. */
 export function applyChunk(
   state: CompositorState,
-  ev: { delta?: string; reasoning?: string; tool?: { id: string; name: string; phase: 'call' | 'result'; ok?: boolean } },
+  ev: { delta?: string; textOperation?: 'replace'; reasoning?: string; tool?: { id: string; name: string; phase: 'call' | 'result'; ok?: boolean } },
 ): void {
-  if (ev.delta) state.text += ev.delta;
+  if (ev.textOperation === 'replace') state.text = ev.delta ?? '';
+  else if (ev.delta) state.text += ev.delta;
   if (ev.reasoning) state.reasoning = ev.reasoning; // keep-latest(추론은 누적 아닌 최신 요약)
   if (ev.tool) {
     if (ev.tool.phase === 'call') {

package/src/session-runtime/index.ts

@@ -185,6 +185,7 @@ export interface SessionRuntimeDispatchDeps {
     dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     workingDirectory: string;
   };
+  inheritGeneralPurposeToolCatalog?: boolean;
   searchPlannerState?: SearchPlannerState;
   /** CC (2026-04-25) — forwarded from the LLM router's dispatch ctx
    *  (`turnIndex`). Lets the planner allow same-turn parallel fan-out
@@ -439,6 +440,7 @@ interface SessionNativeToolRule {
         dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
         workingDirectory: string;
       };
+      inheritGeneralPurposeToolCatalog?: boolean;
     },
   ): Promise<unknown>;
   /** ⛔ Opt-IN to the ToolRuntime registry path instead of `dispatch` above.
@@ -520,6 +522,7 @@ const SESSION_NATIVE_TOOL_RULES: SessionNativeToolRule[] = [
       hostTools: opts?.agentHostTools,
       dispatchTool: opts?.agentDispatchTool,
       buildChildToolCatalog: opts?.buildChildToolCatalog,
+      inheritGeneralPurposeToolCatalog: opts?.inheritGeneralPurposeToolCatalog,
     }),
     preferRuntime: true,
   },
@@ -843,7 +846,7 @@ const SESSION_SURFACE_PROFILES: Record<SessionSurfaceId, Omit<SessionSurfaceProf
     baselineContexts: ['external-world-guidance'],
     defaultHostFamilyIds: ['self-ops'],
     defaultRuntimeFamilyIds: [],
-    defaultNativeFamilyIds: ['web-search'],
+    defaultNativeFamilyIds: ['web-search', 'deep-research', 'web-fetch'],
   },
   'control/agent': {
     id: 'control/agent',
@@ -1811,6 +1814,38 @@ function buildEssentialSessionRuntimeToolSpecs(opts: {
   return [...nativeSpecs, ...hostSpecs, ...runtimeSpecs, ...mcpProxySpecs, ...optionalSpecs];
 }
 
+/** Build the full TUI-visible catalog for Agent children. The parent model's
+ *  turn catalog is intentionally surface/tier narrowed; children inherit the
+ *  available TUI catalog instead, while `dispatchSessionRuntimeTool` remains
+ *  the policy boundary and `dispatchAgent` still strips recursive Agent. */
+export function buildSubagentSessionRuntimeToolSpecs(opts: {
+  hostTools: readonly LLMToolDef[];
+  runtimeTools: readonly ToolRuntime<Record<string, unknown>, ToolRunResult>[];
+  optionalTools: readonly LLMToolSpec[];
+  toolAvailability?: Readonly<Record<string, boolean>>;
+}): LLMToolSpec[] {
+  const nativeSpecs = SESSION_NATIVE_TOOL_RULES.flatMap(rule => {
+    const spec = rule.build();
+    const catalogEntry = findNativeTool(spec.name);
+    return (!catalogEntry || isNativeToolModelExposed(catalogEntry))
+      && isNativeToolAvailable(spec.name, rule, opts.toolAvailability)
+      ? [spec]
+      : [];
+  });
+  const hostSpecs = opts.hostTools
+    .filter(tool => isToolAvailable(tool.name, opts.toolAvailability))
+    .map(toSpec);
+  const runtimeSpecs = opts.runtimeTools
+    .filter(tool => isToolAvailable(tool.spec.name, opts.toolAvailability))
+    .map(tool => tool.spec);
+  const optionalSpecs = opts.optionalTools
+    .filter(tool => isToolAvailable(tool.name, opts.toolAvailability));
+  return [...new Map(
+    [...nativeSpecs, ...hostSpecs, ...runtimeSpecs, ...optionalSpecs]
+      .map(spec => [spec.name, spec] as const),
+  ).values()];
+}
+
 export function buildSessionRuntimeToolSpecs(opts: {
   userText: string;
   hostTools: readonly LLMToolDef[];
@@ -2122,6 +2157,7 @@ export async function dispatchSessionRuntimeTool(
         agentHostTools: deps.agentHostTools,
         agentDispatchTool: deps.agentDispatchTool,
         buildChildToolCatalog: deps.buildChildToolCatalog,
+        inheritGeneralPurposeToolCatalog: deps.inheritGeneralPurposeToolCatalog,
       });
     }
     rememberCandidateListingResult(name, normalizedArgs, result, scopedAnalysis, deps.searchPlannerState);

package/src/session-runtime/retry-policy.ts

@@ -226,7 +226,7 @@ export function providerNamesFromFallbackChain(chain: readonly string[]): string
   const seen = new Set<string>();
   for (const step of chain) {
     // `codex-credits`(체인 마지막 칸 · 크레딧)도 provider 는 openai-codex 다 — 이미 앞에 있으면 중복이라 빠진다.
-    const name = step === 'grok' ? 'grok' : step === 'zai' ? 'glm'
+    const name = step === 'grok' ? 'grok' : step === 'zai' ? 'glm' : step === 'openrouter' ? 'openrouter'
       : step === 'codex-rotate' || step === 'codex-credits' ? 'openai-codex' : undefined;
     if (!name || seen.has(name)) continue;
     seen.add(name);

package/src/setup/llm-env-detect.ts

@@ -168,6 +168,9 @@ export const AUXILIARY_AI_ENV_VARS: readonly AuxiliaryAiEnvVar[] = [
   { name: 'UPSTAGE_API_KEY',    usedBy: 'document parse' },
 ] as const;
 
+export { SERVICE_KEY_CATALOG, renderServiceKeyCatalogMarkdown } from './service-key-catalog.js';
+export type { ServiceKeyCatalogEntry } from './service-key-catalog.js';
+
 export function summarizeAuxiliaryAiEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): AuxiliaryAiEnvVar[] {

package/src/setup/service-key-catalog.ts

@@ -0,0 +1,46 @@
+/** Service setup metadata shared by the CLI, runtime key loader, and manual. */
+export interface ServiceKeyCatalogEntry {
+  id: string;
+  label: string;
+  kind: 'api-key' | 'subscription' | 'oauth' | 'cli' | 'local';
+  envNames: readonly string[];
+  setupUrl: string;
+  usedBy: string;
+  cost: 'account-plan' | 'usage-based' | 'plan-dependent' | 'local';
+  verification: string;
+  demoRequired: boolean;
+}
+
+export const SERVICE_KEY_CATALOG: readonly ServiceKeyCatalogEntry[] = [
+  { id: 'codex', label: 'OpenAI Codex', kind: 'subscription', envNames: [], setupUrl: 'https://platform.openai.com/docs/codex/auth', usedBy: '씬 1 리서치 · 사이드탭 미션', cost: 'account-plan', verification: 'elanous auth status', demoRequired: true },
+  { id: 'claude-code', label: 'Claude Code', kind: 'subscription', envNames: [], setupUrl: 'https://docs.anthropic.com/en/docs/claude-code/overview', usedBy: '씬 1 비교 · 사이드탭 미션', cost: 'account-plan', verification: 'claude auth status', demoRequired: true },
+  { id: 'exa', label: 'Exa', kind: 'api-key', envNames: ['EXA_API_KEY'], setupUrl: 'https://dashboard.exa.ai/api-keys', usedBy: '씬 1 리서치 · 씬 2 흡수', cost: 'usage-based', verification: 'POST /search · 상태 코드만', demoRequired: true },
+  { id: 'firecrawl', label: 'Firecrawl', kind: 'api-key', envNames: ['FIRECRAWL_API_KEY'], setupUrl: 'https://www.firecrawl.dev/app/api-keys', usedBy: '씬 2 흡수', cost: 'usage-based', verification: 'POST /v2/scrape · 상태 코드만', demoRequired: true },
+  { id: 'xai', label: 'xAI / Grok API', kind: 'api-key', envNames: ['XAI_API_KEY', 'GROK_API_KEY'], setupUrl: 'https://console.x.ai/', usedBy: '씬 2 흡수 · Grok API', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: true },
+  { id: 'tavily', label: 'Tavily', kind: 'api-key', envNames: ['TAVILY_API_KEY', 'TAVILY_KEY'], setupUrl: 'https://app.tavily.com/home', usedBy: '웹 검색 대체 경로', cost: 'usage-based', verification: 'POST /search · 상태 코드만', demoRequired: false },
+  { id: 'openrouter', label: 'OpenRouter · GLM', kind: 'api-key', envNames: ['OPENROUTER_API_KEY'], setupUrl: 'https://openrouter.ai/keys', usedBy: 'GLM · OpenRouter 모델', cost: 'usage-based', verification: 'GET /api/v1/key · 상태 코드만', demoRequired: true },
+  { id: 'linear', label: 'Linear API', kind: 'api-key', envNames: ['LINEAR_API_KEY'], setupUrl: 'https://linear.app/settings/api', usedBy: '씬 2 능동 비서', cost: 'plan-dependent', verification: 'GraphQL viewer · 상태 코드만', demoRequired: true },
+  { id: 'telegram', label: 'Telegram bot', kind: 'api-key', envNames: ['ELANOUS_TELEGRAM_BOT_TOKEN'], setupUrl: 'https://t.me/BotFather', usedBy: '씬 2 · 씬 3 채널', cost: 'local', verification: 'getMe · 상태 코드만', demoRequired: true },
+  { id: 'telegram-chat', label: 'Telegram chat ID', kind: 'api-key', envNames: ['ELANOUS_TELEGRAM_CHAT_ID'], setupUrl: 'https://core.telegram.org/bots/features#botfather', usedBy: '데모 알림 대상', cost: 'local', verification: 'getChat · 상태 코드만 · 미발송', demoRequired: true },
+  { id: 'google-workspace', label: 'Google Workspace', kind: 'oauth', envNames: [], setupUrl: 'https://developers.google.com/workspace/guides/get-started', usedBy: 'Gmail · Drive 커넥터', cost: 'account-plan', verification: '로그인 상태 확인 · 토큰 미표시', demoRequired: false },
+  { id: 'aside', label: 'Aside browser', kind: 'cli', envNames: [], setupUrl: 'https://github.com/elanous-ai/aside', usedBy: '브라우저 자동화', cost: 'plan-dependent', verification: 'aside status', demoRequired: true },
+  { id: 'github', label: 'GitHub CLI', kind: 'cli', envNames: [], setupUrl: 'https://cli.github.com/', usedBy: '공개 저장소 · 개발 플러그인', cost: 'local', verification: 'gh auth status', demoRequired: true },
+  { id: 'video-render', label: 'Video render', kind: 'local', envNames: [], setupUrl: 'https://ffmpeg.org/download.html', usedBy: '데모 하이라이트 렌더', cost: 'local', verification: 'ffmpeg -version', demoRequired: false },
+  { id: 'openai-api', label: 'OpenAI API', kind: 'api-key', envNames: ['OPENAI_API_KEY'], setupUrl: 'https://platform.openai.com/api-keys', usedBy: 'OpenAI 모델 · Codex API-key 경로', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'anthropic-api', label: 'Anthropic API', kind: 'api-key', envNames: ['ANTHROPIC_API_KEY'], setupUrl: 'https://console.anthropic.com/settings/keys', usedBy: 'Claude API', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'gemini-api', label: 'Google Gemini API', kind: 'api-key', envNames: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'], setupUrl: 'https://aistudio.google.com/app/apikey', usedBy: 'Gemini 모델', cost: 'usage-based', verification: '모델 목록 · 상태 코드만', demoRequired: false },
+  { id: 'opengateway', label: 'OpenGateway', kind: 'api-key', envNames: ['OPENGATEWAY_API_KEY'], setupUrl: 'https://apis.opengateway.ai/', usedBy: 'OpenAI 호환 모델 대체 경로', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'supadata', label: 'Supadata', kind: 'api-key', envNames: ['SUPADATA_API_KEY'], setupUrl: 'https://supadata.ai/', usedBy: 'YouTube 자막', cost: 'usage-based', verification: '자막 API · 상태 코드만', demoRequired: false },
+  { id: 'elevenlabs', label: 'ElevenLabs', kind: 'api-key', envNames: ['ELEVENLABS_API_KEY'], setupUrl: 'https://elevenlabs.io/app/settings/api-keys', usedBy: '음성 합성', cost: 'usage-based', verification: 'GET /v1/user · 상태 코드만', demoRequired: false },
+  { id: 'brave-search', label: 'Brave Search', kind: 'api-key', envNames: ['BRAVE_API_KEY'], setupUrl: 'https://brave.com/search/api/', usedBy: '웹 검색 대체 경로', cost: 'usage-based', verification: '검색 API · 상태 코드만', demoRequired: false },
+  { id: 'youtube-data', label: 'YouTube Data API', kind: 'api-key', envNames: ['YOUTUBE_API_KEY'], setupUrl: 'https://console.cloud.google.com/apis/credentials', usedBy: 'YouTube 메타데이터', cost: 'usage-based', verification: 'videos.list · 상태 코드만', demoRequired: false },
+  { id: 'apify', label: 'Apify', kind: 'api-key', envNames: ['APIFY_TOKEN'], setupUrl: 'https://console.apify.com/account/integrations', usedBy: 'X 수집', cost: 'usage-based', verification: '사용자 API · 상태 코드만', demoRequired: false },
+  { id: 'eodhd', label: 'EODHD', kind: 'api-key', envNames: ['EODHD_API_KEY'], setupUrl: 'https://eodhd.com/financial-apis/', usedBy: '시장 시세', cost: 'usage-based', verification: '시장 API · 상태 코드만', demoRequired: false },
+  { id: 'fds', label: 'FDS market data', kind: 'api-key', envNames: ['FDS_API_KEY'], setupUrl: 'https://elanous.ai', usedBy: '시장 시세', cost: 'plan-dependent', verification: '연결 미니 호출 · 상태 코드만', demoRequired: false },
+  { id: 'upstage', label: 'Upstage', kind: 'api-key', envNames: ['UPSTAGE_API_KEY'], setupUrl: 'https://console.upstage.ai/api-keys', usedBy: '문서 파싱', cost: 'usage-based', verification: '문서 API · 상태 코드만', demoRequired: false },
+] as const;
+
+export function renderServiceKeyCatalogMarkdown(): string {
+  const rows = SERVICE_KEY_CATALOG.map(item => `| ${item.id} | ${item.label} | ${item.kind} | ${item.envNames.join(', ') || '로그인/설치'} | ${item.setupUrl} | ${item.cost} | ${item.usedBy} | ${item.verification} | ${item.demoRequired ? '씬 사용' : '선택'} |`);
+  return ['| id | 서비스 | 인증 | 환경 이름 | 설정 위치 | 비용 유형 | 사용처 | 최소 확인 | 판정 |', '|---|---|---|---|---|---|---|---|---|', ...rows].join('\n');
+}