elanous 0.2.41 → 0.2.42

package/scripts/warm-pool-provider-config.ts

@@ -0,0 +1,263 @@
+import { spawn } from 'node:child_process';
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { userConfigPath } from '../src/user-config.js';
+
+const TOKEN = /^[a-f0-9]{64}$/;
+const SHA = /^[a-f0-9]{40}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const LOCK_HASH = /^[a-f0-9]{64}$/;
+const TIERS = new Set(['lite', 'standard']);
+
+type JsonObject = Record<string, unknown>;
+
+export interface WarmPoolProviderConfig {
+  candidates: [];
+  poolTemplates: Array<{
+    host: string;
+    tier: 'lite' | 'standard';
+    spec: {
+      name: string;
+      namespace: string;
+      kubectlContext: string;
+      workerId: string;
+      image: string;
+      sourceUrl?: string;
+      sourceMirrorHostPath?: string;
+      nodeName: string;
+      cutSha: string;
+      key: { context: string; imageDigest: string; lockHash: string; architecture: string };
+      memoryLimit: '2Gi' | '16Gi';
+      hostProbeUrl: string;
+      prodProbeUrl: string;
+    };
+  }>;
+  profileConfig: { pod: { warmPoolProfile: string } };
+  controlUrl: string;
+  memberToken: string;
+  machineTokens: Record<string, string>;
+}
+
+export interface AssembleWarmPoolProviderConfigInput {
+  config: unknown;
+  controlUrl: string;
+  memberToken: string;
+  machineTokens: Record<string, string>;
+}
+
+function object(value: unknown, label: string): JsonObject {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} is required`);
+  return value as JsonObject;
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+function token(value: unknown, label: string): string {
+  const parsed = text(value, label);
+  if (!TOKEN.test(parsed)) throw new Error(`${label} must be a 64-character hexadecimal token`);
+  return parsed;
+}
+
+function httpUrl(value: unknown, label: string, hostname?: string): string {
+  const parsed = text(value, label);
+  try {
+    const url = new URL(parsed);
+    if (url.protocol !== 'http:' || !url.port || url.username || url.password || url.search || url.hash
+      || (hostname !== undefined && url.hostname !== hostname)) throw new Error();
+    return url.href;
+  } catch { throw new Error(`${label} must be an http URL${hostname ? ` for ${hostname}` : ''}`); }
+}
+
+function controlUrl(value: unknown): string {
+  const parsed = text(value, 'controlUrl');
+  try {
+    const url = new URL(parsed);
+    const authority = /^(?:http|https):\/\/([^/?#]*)/i.exec(parsed)?.[1] ?? '';
+    const explicitPort = !authority.includes('\\') && /^(?:\[[^\]]+\]|[^:]+):\d+$/.test(authority);
+    if (!['http:', 'https:'].includes(url.protocol) || !explicitPort || authority.includes('@') || url.username || url.password
+      || parsed.includes('?') || parsed.includes('#') || url.search || url.hash)
+      throw new Error();
+    return url.href;
+  } catch { throw new Error('controlUrl must be an http or https URL with an explicit port'); }
+}
+
+function privateSource(pool: JsonObject): Pick<WarmPoolProviderConfig['poolTemplates'][number]['spec'], 'sourceUrl' | 'sourceMirrorHostPath'> {
+  const mirror = pool.sourceMirrorHostPath;
+  const source = pool.sourceUrl;
+  if (typeof mirror === 'string' && mirror.trim()) {
+    if (!isAbsolute(mirror) || mirror.trim() !== mirror) throw new Error('pod.warmPool.sourceMirrorHostPath must be an absolute normalized path');
+    return { sourceMirrorHostPath: mirror };
+  }
+  if (typeof source === 'string' && source.trim()) {
+    try {
+      const url = new URL(source);
+      if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search || url.hash) throw new Error();
+      return { sourceUrl: url.href };
+    } catch { throw new Error('pod.warmPool.sourceUrl must be a public https URL'); }
+  }
+  throw new Error('pod.warmPool.sourceMirrorHostPath or pod.warmPool.sourceUrl is required');
+}
+
+/** Convert canonical user config plus operator-supplied private credentials into the two provider loaders' shared format. */
+export function assembleWarmPoolProviderConfig(input: AssembleWarmPoolProviderConfigInput): WarmPoolProviderConfig {
+  const root = object(input.config, 'config');
+  const pod = object(root.pod, 'pod');
+  const harness = object(root.harness, 'harness');
+  const profile = text(pod.warmPoolProfile, 'pod.warmPoolProfile');
+  const pool = object(pod.warmPool, 'pod.warmPool');
+  const cutSha = text(harness.imageCommit, 'harness.imageCommit');
+  if (!SHA.test(cutSha)) throw new Error('harness.imageCommit must be a 40-character commit SHA');
+  const kubectlContext = text(harness.podPool, 'harness.podPool');
+  const namespace = text(pool.namespace, 'pod.warmPool.namespace');
+  const imageRepository = text(pool.imageRepository, 'pod.warmPool.imageRepository').replace(/\/$/, '');
+  const imageDigest = text(pool.imageDigest, 'pod.warmPool.imageDigest');
+  if (!DIGEST.test(imageDigest)) throw new Error('pod.warmPool.imageDigest must be a sha256 digest');
+  const lockHash = text(pool.lockHash, 'pod.warmPool.lockHash');
+  if (!LOCK_HASH.test(lockHash)) throw new Error('pod.warmPool.lockHash must be a 64-character SHA-256');
+  const architecture = text(pool.architecture, 'pod.warmPool.architecture');
+  const hostProbeUrl = httpUrl(pool.hostProbeUrl, 'pod.warmPool.hostProbeUrl', 'host.orb.internal');
+  const prodProbeUrl = httpUrl(pool.prodProbeUrl, 'pod.warmPool.prodProbeUrl', 'core.elanous-prod');
+  const source = privateSource(pool);
+  const templates = pool.templates;
+  if (!Array.isArray(templates) || templates.length === 0) throw new Error('pod.warmPool.templates is required');
+  const seen = new Set<string>();
+  const machineTokens: Record<string, string> = {};
+  const poolTemplates = templates.map((raw, index) => {
+    const row = object(raw, `pod.warmPool.templates[${index}]`);
+    const host = text(row.host, `pod.warmPool.templates[${index}].host`);
+    const tier = text(row.tier, `pod.warmPool.templates[${index}].tier`);
+    if (!TIERS.has(tier)) throw new Error(`pod.warmPool.templates[${index}].tier must be lite or standard`);
+    const nodeName = text(row.nodeName, `pod.warmPool.templates[${index}].nodeName`);
+    const identity = `${host}/${tier}`;
+    if (seen.has(identity)) throw new Error(`duplicate pod.warmPool template ${identity}`);
+    seen.add(identity);
+    machineTokens[host] = token(input.machineTokens[host], `machine token for ${host}`);
+    return {
+      host,
+      tier: tier as 'lite' | 'standard',
+      spec: {
+        name: `warm-${host}-${tier}-template`, namespace, kubectlContext,
+        workerId: `warm-${host}-${cutSha.slice(0, 12)}`, image: `${imageRepository}@${imageDigest}`,
+        ...source, nodeName, cutSha,
+        key: { context: kubectlContext, imageDigest, lockHash, architecture },
+        memoryLimit: tier === 'lite' ? '2Gi' as const : '16Gi' as const,
+        hostProbeUrl, prodProbeUrl,
+      },
+    };
+  });
+  return { candidates: [], poolTemplates, profileConfig: { pod: { warmPoolProfile: profile } },
+    controlUrl: controlUrl(input.controlUrl), memberToken: token(input.memberToken, 'member token'), machineTokens };
+}
+
+/** Atomically replace the private provider config and repair permissions on an existing file. */
+export function writeWarmPoolProviderConfig(path: string, config: WarmPoolProviderConfig): void {
+  if (!isAbsolute(path)) throw new Error('output path must be absolute');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* no temporary output */ }
+    throw error;
+  }
+}
+
+function redact(config: WarmPoolProviderConfig): unknown {
+  return { ...config, memberToken: '[redacted]', machineTokens: Object.fromEntries(Object.keys(config.machineTokens).map(host => [host, '[redacted]'])) };
+}
+
+function shellQuote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+interface CliOptions {
+  configPath: string;
+  controlUrl: string;
+  memberTokenFile: string;
+  machineTokenFiles: Record<string, string>;
+  output: string;
+  dryRun: boolean;
+  serve: boolean;
+}
+
+function parseArgs(argv: readonly string[]): CliOptions {
+  let configPath = userConfigPath(), controlUrl = '', memberTokenFile = '', output = '';
+  let dryRun = false, serve = false;
+  const machineTokenFiles: Record<string, string> = {};
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    const next = () => {
+      const value = argv[++index];
+      if (!value) throw new Error(`missing value for ${arg}`);
+      return value;
+    };
+    if (arg === '--config') configPath = next();
+    else if (arg === '--control-url') controlUrl = next();
+    else if (arg === '--member-token-file') memberTokenFile = next();
+    else if (arg === '--machine-token') {
+      const [host, file, extra] = next().split('=');
+      if (!host || !file || extra !== undefined) throw new Error('--machine-token must be HOST=FILE');
+      machineTokenFiles[host] = file;
+    } else if (arg === '--output') output = next();
+    else if (arg === '--dry-run') dryRun = true;
+    else if (arg === '--serve') serve = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!isAbsolute(configPath) || !controlUrl || !isAbsolute(memberTokenFile))
+    throw new Error('usage: --config ABSOLUTE --control-url URL --member-token-file ABSOLUTE --machine-token HOST=ABSOLUTE [--output ABSOLUTE] [--dry-run|--serve]');
+  if (Object.values(machineTokenFiles).some(file => !isAbsolute(file))) throw new Error('machine token files must be absolute');
+  if (dryRun && serve) throw new Error('--dry-run and --serve cannot be combined');
+  return { configPath, controlUrl, memberTokenFile, machineTokenFiles,
+    output: output || join(dirname(configPath), 'warm-pod-provider.json'), dryRun, serve };
+}
+
+function readPrivateToken(path: string, label: string): string {
+  if (!isAbsolute(path)) throw new Error(`${label} path must be absolute`);
+  return token(readFileSync(path, 'utf8').trim(), label);
+}
+
+export async function runWarmPoolProviderConfig(argv: readonly string[]): Promise<void> {
+  const options = parseArgs(argv);
+  const config = JSON.parse(readFileSync(options.configPath, 'utf8')) as unknown;
+  const machineTokens = Object.fromEntries(Object.entries(options.machineTokenFiles)
+    .map(([host, path]) => [host, readPrivateToken(path, `machine token for ${host}`)]));
+  const assembled = assembleWarmPoolProviderConfig({ config, controlUrl: options.controlUrl,
+    memberToken: readPrivateToken(options.memberTokenFile, 'member token'), machineTokens });
+  if (!options.dryRun) writeWarmPoolProviderConfig(options.output, assembled);
+  process.stdout.write(`${JSON.stringify({ output: options.output, config: redact(assembled),
+    ...(options.serve ? { serve: { command: `ELANOUS_WARM_POD_PROVIDER_CONFIG=${shellQuote(options.output)} bun src/task-orchestrator/surfaces/pod-warm-worker-provider.ts --serve` } } : {}) })}\n`);
+  if (!options.serve) return;
+  const provider = fileURLToPath(new URL('../src/task-orchestrator/surfaces/pod-warm-worker-provider.ts', import.meta.url));
+  const child = spawn(process.execPath, [provider, '--serve'], { stdio: 'inherit',
+    env: { ...process.env, ELANOUS_WARM_POD_PROVIDER_CONFIG: options.output } });
+  const forwardSignal = (signal: NodeJS.Signals) => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); };
+  const forwardInterrupt = () => forwardSignal('SIGINT');
+  const forwardTerminate = () => forwardSignal('SIGTERM');
+  process.on('SIGINT', forwardInterrupt);
+  process.on('SIGTERM', forwardTerminate);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', (code, signal) => {
+        process.exitCode = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 2);
+        resolve();
+      });
+    });
+  } finally {
+    process.off('SIGINT', forwardInterrupt);
+    process.off('SIGTERM', forwardTerminate);
+  }
+}
+
+if (import.meta.main) {
+  try { await runWarmPoolProviderConfig(process.argv.slice(2)); }
+  catch (error) {
+    process.stderr.write(`warm-pool-provider-config: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+  }
+}

package/skills/omni-crawl/SKILL.md

@@ -81,13 +81,16 @@ requires: []
 자체 합성 파이프라인 (Tavily Research 엔드포인트 미사용 — 콜당 15~250cr 폭탄 회피):
 
 ```
-1) 다각도 tavily advanced ×3 (core/outlook/risk) 병렬   ~6cr  ⚙️ OMNI_CRAWL_TAVILY=0 이면 ddg 무료 ×3 (0cr)
-2) URL dedup → 상위 5개 firecrawl 풀스크랩 (캐시 2h)     ~5cr
+1) 다각도 검색 ×3 (Tavily 사용 가능 시 Tavily, 키 없음/비활성 시 Firecrawl) 병렬
+   런타임 0건/실패면 다음 유료 엔진, 두 검색축이 모두 비었을 때만 DDG 무료 최후 폴백
+2) URL dedup → 상위 5개 Firecrawl 풀스크랩 (캐시 2h)
 3) grok-community 1콜 (X+레딧 여론 각도)                 ~$0.05
 4) 기술 주제면 fc-dev 1콜 자동 가세 (looksTechnical 게이트)  ~2cr
 → 통합 마크다운 (풀본문이 스니펫보다 dedup 우선 생존)
 ```
 
+각 각도 검색과 URL 스크랩은 엔진·단계별 경과 시간을 로그에 남긴다. Tavily 키가 없는 정상 경로는 Firecrawl 검색으로 세 각도를 채우며, DDG는 Tavily와 Firecrawl이 모두 없거나 0건일 때만 최후 폴백으로 호출한다.
+
 ## 실행
 
 이 스킬 폴더에서 실행합니다.

package/skills/omni-crawl/scripts/main.ts

@@ -153,7 +153,7 @@ async function main(query: string) {
 
 // ── Deep research 파이프라인 (자체 합성 — Tavily Research 엔드포인트 미사용·비용 예측성) ──
 //
-// 1) 다각도 tavily advanced ×3 (사실/전망/리스크 각도) 병렬
+// 1) 다각도 웹 검색 ×3 (Tavily 사용 가능 시 Tavily, 아니면 Firecrawl) 병렬
 // 2) URL dedup → 상위 K=5 를 firecrawl 풀스크랩 (maxAge 2h 캐시)
 // 3) grok-community 1콜 (X+레딧 여론 각도)
 // 카버당 비용: tavily ~6cr + firecrawl ~5cr + grok ~$0.03 — 예측 가능.
@@ -173,15 +173,11 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
   const results: CrawlResult[] = [];
 
   // 1) 다각도 검색 + grok-community 동시 발사
-  // ⛔⭐ 2026-08-06 (공식 결정) — tavily 각도 검색은 **기본 OFF**(deep 1회당 advanced ×3 ≈ 6cr 고정비).
-  //    켜기: `.env` 또는 셸에 `OMNI_CRAWL_TAVILY=1`. 끄면 아래 `!gotTavily` 분기가 **이미 있는**
-  //    ddg 무료 각도 검색을 대신 돌린다(별도 배선 불필요).
+  // 키 부재·비활성뿐 아니라 Tavily/Firecrawl 런타임 공백도 다음 엔진으로 넘긴다.
+  // Tavily 부재 시 Firecrawl이 우선이며 DDG는 두 유료 검색축이 모두 비었을 때만 최후 폴백.
+  const angleEngines = deepAngleSearchOrder(tavilyEnabled() && tavilyAvailable(), firecrawlAvailable());
   const searchTasks: Array<Promise<CrawlResult | null>> = [
-    ...(tavilyEnabled() ? angles.map(a =>
-      searchTavily(a.q, { depth: 'advanced', maxResults: 5, chunksPerSource: 3, timeRange: flags['time-range'] })
-        .then(r => ({ ...r, engine: `tavily:${a.label}` }))
-        .catch(e => { console.log(`  [deep] tavily(${a.label}) 실패: ${e.message?.slice(0, 80)}`); return null; }),
-    ) : []),
+    ...angles.map(a => searchDeepAngle(a, angleEngines)),
     searchGrok({ query, mode: 'community' })
       .catch(e => { console.log(`  [deep] grok-community 실패: ${e.message?.slice(0, 80)}`); return null; }),
     // 기술 주제면 개발자 인덱스 1콜 추가(실측 ~2cr) — 패시지가 곧 인용이라 풀스크랩 콜을 아낀다.
@@ -193,20 +189,11 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
   const settled = await Promise.all(searchTasks);
   for (const r of settled) if (r) results.push(r as CrawlResult);
 
-  // 1-b) tavily 축이 비면(기본 OFF · 키 없음 · 장애) ddg 무료가 각도 검색을 담당한다.
-  const gotTavily = results.some(r => r.engine.startsWith('tavily') && r.totalItems > 0);
-  if (!gotTavily) {
-    console.log('  [deep] ddg 무료 티어로 각도 검색');
-    const ddgResults = await Promise.all(angles.map(a =>
-      searchDdg(a.q, { maxResults: 5 }).then(r => ({ ...r, engine: `ddg:${a.label}` })).catch(() => null)));
-    for (const r of ddgResults) if (r && r.totalItems > 0) results.push(r as CrawlResult);
-  }
-
   // 2) 검색 히트에서 상위 URL 추출 → firecrawl 풀스크랩 (병렬·캐시 2h)
   const seen = new Set<string>();
   const topUrls: string[] = [];
   for (const r of results) {
-    if (!r.engine.startsWith('tavily') && !r.engine.startsWith('ddg')) continue;
+    if (!r.engine.startsWith('tavily') && !r.engine.startsWith('firecrawl') && !r.engine.startsWith('ddg')) continue;
     for (const it of r.items) {
       if (!it.url || seen.has(it.url)) continue;
       seen.add(it.url);
@@ -217,9 +204,21 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
   }
   if (topUrls.length) {
     console.log(`  [deep] 상위 ${topUrls.length}개 URL 풀스크랩 (firecrawl·캐시 2h)`);
-    const scraped = await Promise.all(topUrls.map(u =>
-      scrapeFirecrawl(u, { maxAge: 2 * 3600_000 }).catch(() => null),
-    ));
+    const scraped = await Promise.all(topUrls.map(async u => {
+      const startedAt = Date.now();
+      try {
+        const result = await scrapeFirecrawl(u, { maxAge: 2 * 3600_000 });
+        if (!result) {
+          console.log(`  [deep:firecrawl:scrape] ${u} · 실패 · ${Date.now() - startedAt}ms · 본문 없음`);
+          return null;
+        }
+        console.log(`  [deep:firecrawl:scrape] ${u} · ${Date.now() - startedAt}ms · ${result.content.length}자`);
+        return result;
+      } catch (e: any) {
+        console.log(`  [deep:firecrawl:scrape] ${u} · 실패 · ${Date.now() - startedAt}ms · ${e.message?.slice(0, 80)}`);
+        return null;
+      }
+    }));
     const items: CrawlItem[] = [];
     for (let i = 0; i < scraped.length; i++) {
       const s = scraped[i];
@@ -248,12 +247,54 @@ async function runDeep(query: string): Promise<CrawlResult[]> {
         if (s) items.push({ engine: 'fc-deep', query, url: missed[i], text: s.content.slice(0, 6000), metadata: { via: s.method, title: s.title } });
       }
     }
-    if (items.length) results.push({ engine: 'deep-fullscrape', query, items, totalItems: items.length, costNote: `firecrawl ~${scraped.filter(Boolean).length}cr + 무료` });
+    if (items.length) {
+      console.log(`  [deep:firecrawl:fullscrape] ${items.length}/${topUrls.length}건 본문 확보`);
+      results.push({ engine: 'deep-fullscrape', query, items, totalItems: items.length, costNote: `firecrawl ~${scraped.filter(Boolean).length}cr + 무료` });
+    } else {
+      console.log(`  [deep:firecrawl:fullscrape] 0/${topUrls.length}건 본문 확보`);
+    }
   }
 
   return results;
 }
 
+type DeepAngleEngine = 'tavily' | 'firecrawl' | 'ddg';
+
+function deepAngleSearchOrder(tavilyReady: boolean, firecrawlReady: boolean): DeepAngleEngine[] {
+  return [
+    ...(tavilyReady ? ['tavily' as const] : []),
+    ...(firecrawlReady ? ['firecrawl' as const] : []),
+    'ddg',
+  ];
+}
+
+function firecrawlTbsFromTimeRange(timeRange?: string): string | undefined {
+  if (!timeRange) return undefined;
+  return ({ day: 'qdr:d', week: 'qdr:w', month: 'qdr:m', year: 'qdr:y' } as Record<string, string>)[timeRange];
+}
+
+async function searchDeepAngle(
+  angle: { q: string; label: string },
+  engines: DeepAngleEngine[],
+): Promise<CrawlResult | null> {
+  for (const engine of engines) {
+    const startedAt = Date.now();
+    try {
+      const result = engine === 'tavily'
+        ? await searchTavily(angle.q, { depth: 'advanced', maxResults: 5, chunksPerSource: 3, timeRange: flags['time-range'] })
+        : engine === 'firecrawl'
+          ? await searchFirecrawl(angle.q, { limit: 5, tbs: firecrawlTbsFromTimeRange(flags['time-range']) })
+          : await searchDdg(angle.q, { maxResults: 5 });
+      const elapsedMs = Date.now() - startedAt;
+      console.log(`  [deep:${engine}:${angle.label}] ${result.totalItems}건 · ${elapsedMs}ms`);
+      if (result.totalItems > 0) return { ...result, engine: `${engine}:${angle.label}` };
+    } catch (e: any) {
+      console.log(`  [deep:${engine}:${angle.label}] 실패 · ${Date.now() - startedAt}ms · ${e.message?.slice(0, 80)}`);
+    }
+  }
+  return null;
+}
+
 // ── 폴백 체인: tavily ↔ firecrawl → (최후) ddg 무료 (웹 검색 축 공백 방지) ──
 //
 // 원칙: 유료(tavily/firecrawl)가 1순위·기본. 유료가 공백/미가용일 때만 무료(ddg)로 강등.
@@ -494,6 +535,26 @@ function runSelfTest() {
     else { console.log(`  FAIL: looksTechnical("${q}") expect ${expect}, got ${got}`); failed++; }
   }
 
+  const angleEngineCases: Array<[string, boolean, boolean, string]> = [
+    ['Tavily and Firecrawl ready', true, true, 'tavily,firecrawl,ddg'],
+    ['Tavily unavailable', false, true, 'firecrawl,ddg'],
+    ['Tavily disabled', false, true, 'firecrawl,ddg'],
+    ['both paid search engines unavailable', false, false, 'ddg'],
+  ];
+  for (const [label, tavilyReady, firecrawlReady, expected] of angleEngineCases) {
+    const got = deepAngleSearchOrder(tavilyReady, firecrawlReady).join(',');
+    if (got === expected) { console.log(`  PASS: deep angle fallback ${label} → ${got}`); passed++; }
+    else { console.log(`  FAIL: deep angle fallback ${label} expect ${expected}, got ${got}`); failed++; }
+  }
+  const tbsCases: Array<[string, string | undefined]> = [
+    ['day', 'qdr:d'], ['week', 'qdr:w'], ['month', 'qdr:m'], ['year', 'qdr:y'], ['unset', undefined],
+  ];
+  for (const [timeRange, expected] of tbsCases) {
+    const got = firecrawlTbsFromTimeRange(timeRange === 'unset' ? undefined : timeRange);
+    if (got === expected) { console.log(`  PASS: Firecrawl time range ${timeRange} → ${got ?? 'unset'}`); passed++; }
+    else { console.log(`  FAIL: Firecrawl time range ${timeRange} expect ${expected}, got ${got}`); failed++; }
+  }
+
   console.log(`\n결과: ${passed} passed, ${failed} failed`);
   if (failed > 0) process.exit(1);
 }

package/src/acp/core-turn-bridge.ts

@@ -38,6 +38,7 @@ import { nextTurnFallbackProvider, resolveDefaultProvider, type LLMMessage, type
 import { readAutohealProviderFallback } from '../self-health/autoheal.js';
 import { debug, redactSecretText } from '../debug/log.js';
 import { CoreTurnAuthRejectedError } from '../core-turn/auth-rejected-notice.js';
+import { globalTaskNotificationQueue, renderTaskNotificationsXml } from '../agent/task-notification.js';
 import {
   runCoreTurn,
   runGoalLoop,
@@ -452,6 +453,11 @@ export function bridgeCoreTurnToAcp(
           ? runGoalLoop(c, {
               // ACP owns an interactive provider loop: keep its post-completion response contract.
               terminalCompletionShortcut: false,
+              drainIterationMessages: () => {
+                const pending = globalTaskNotificationQueue.drainForParentSessionOrUnscoped(c.sessionId);
+                const xml = renderTaskNotificationsXml(pending);
+                return xml ? [{ role: 'user', content: xml }] : [];
+              },
               ...(goalLoopCfg?.maxIterations !== undefined ? { maxIterations: goalLoopCfg.maxIterations } : {}),
               // #29 처방 — 자리 판정으로 goal loop 에 «되돌아온» 턴만 빈 evidence 완료를 답으로 받는다.
               ...(route.reason.startsWith('seat-') ? { lenientCompletionEvidence: true } : {}),
@@ -543,6 +549,13 @@ export function bridgeCoreTurnToAcp(
             streamedTextSum += delta;
             void turnCtx.push(delta);
           },
+          onReplaceText: (full) => {
+            reasoningThoughts.flush();
+            streamedTextSum = full;
+            // Match the existing ACP clear/replace convention used for final synthesis.
+            void turnCtx.push('');
+            void turnCtx.push(full);
+          },
           // P2-bridge-ext — forward tool + usage events as ACP
           // sessionUpdate notifications so extension-aware clients
           // (dashboard as ACP client / future web / iphone) can

package/src/agent/registry.ts

@@ -123,6 +123,7 @@ export class AgentRegistry {
       id: randomUUID(),
       definition: opts.definition,
       prompt: opts.prompt,
+      ...(opts.parentSessionId ? { parentSessionId: opts.parentSessionId } : {}),
       depth,
       ...(opts.label ? { label: opts.label } : {}),
       ...(opts.correlationId ? { correlationId: opts.correlationId } : {}),
@@ -136,6 +137,7 @@ export class AgentRegistry {
       ...(opts.teamName ? { teamName: opts.teamName } : {}),
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
       ...(opts.background ? { background: true } : {}),
+      ...(opts.completionDelivery ? { completionDelivery: opts.completionDelivery } : {}),
       // MSS M1.2: brand the spawn with an AgentUri (caller may pre-mint
       // for cross-task tracing; default = fresh mint). The legacy UUID
       // `id` stays the registry key — agentUri rides alongside.

package/src/agent/task-notification.ts

@@ -5,7 +5,7 @@
 // "(running in background)" message on the same turn. To surface the
 // eventual result, we collect a `PendingTaskNotification` per completed
 // background task and inject a `<task-notification>` XML user message
-// at the start of the parent's NEXT turn.
+// at the start of the parent's next turn or at a live goal-loop boundary.
 //
 // Why XML injection instead of a tool ──
 //  • Tool-loop parents would need to remember to poll; the reliability
@@ -43,11 +43,14 @@ export const TASK_NOTIFICATION_OUTPUT_CAP = 500;
 
 export interface PendingTaskNotification {
   taskId: string;
+  parentSessionId?: string;
   agentName: string;
   /** Caller-supplied short label (Agent tool's `name` arg). */
   label?: string;
   /** Team context this task belonged to (Agent tool's `team_name`). */
   teamName?: string;
+  /** Parent-selected route; supplemental results never reopen a TUI turn. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** Final state of the task — parent LLM sees this to choose follow-up. */
   state: 'done' | 'error' | 'aborted';
   /** Child's final text (capped at TASK_NOTIFICATION_OUTPUT_CAP). */
@@ -150,11 +153,26 @@ export class TaskNotificationQueue {
     }
   }
 
-  /** Return all pending notifications AND clear the queue. Parents
-   *  call this exactly once per turn-start. */
+  /** Return all pending notifications and remove them from the queue. */
   drain(): PendingTaskNotification[] {
-    const out = this.queue;
-    this.queue = [];
+    return this.drainMatching(() => true);
+  }
+
+  /** Drain only results owned by one parent session; leave sibling sessions queued. */
+  drainForParentSession(parentSessionId: string): PendingTaskNotification[] {
+    return this.drainMatching((item) => item.parentSessionId === parentSessionId);
+  }
+
+  /** Drain one session's receipts plus legacy sessionless receipts; keep sibling sessions queued. */
+  drainForParentSessionOrUnscoped(parentSessionId: string): PendingTaskNotification[] {
+    return this.drainMatching((item) => item.parentSessionId === undefined || item.parentSessionId === parentSessionId);
+  }
+
+  private drainMatching(matches: (item: PendingTaskNotification) => boolean): PendingTaskNotification[] {
+    const out = this.queue.filter(matches);
+    if (out.length === 0) return out;
+    const drained = new Set(out);
+    this.queue = this.queue.filter((item) => !drained.has(item));
     this.persist();
     // NOTE: we keep `seen` populated so a listener firing a second
     // time for the same task (rare but possible under races) still
@@ -260,9 +278,11 @@ function buildPendingFromTask(task: AgentTask): PendingTaskNotification | null {
   const output = task.result ?? '';
   return {
     taskId: task.id,
+    ...(task.parentSessionId ? { parentSessionId: task.parentSessionId } : {}),
     agentName: task.definition.name,
     ...(task.label ? { label: task.label } : {}),
     ...(task.teamName ? { teamName: task.teamName } : {}),
+    ...(task.completionDelivery ? { completionDelivery: task.completionDelivery } : {}),
     state,
     output,
     truncated: false,

package/src/agent/types.ts

@@ -154,6 +154,8 @@ export interface AgentTask {
    *  the runner drains events in the background; completion emits
    *  a task-notification (PFC-S1 P2). */
   background?: boolean;
+  /** How a background completion reaches an idle parent TUI. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** MSS M1.2: branded URI form of this spawn's identity. The
    *  registry mints one alongside the UUID-keyed `id`. Downstream
    *  MSS bridges (M3 signal sender · M4 memory participant) reference
@@ -183,6 +185,8 @@ export interface AgentSpawnOpts {
   definition: AgentDefinition;
   /** User message / query the agent should answer. */
   prompt: string;
+  /** Session that owns this spawn; scopes background completion delivery. */
+  parentSessionId?: string;
   /** Short task label — used by UI panes (e.g. agent-roster in
    *  wd-scratch) to distinguish spawns that share a definition.
    *  Stored verbatim on AgentTask.label. Optional; when omitted,
@@ -225,6 +229,8 @@ export interface AgentSpawnOpts {
    *  immediately and drains events off-thread. Completion emits a
    *  task-notification (see src/agent/task-notification.ts, P2). */
   background?: boolean;
+  /** Parent-selected routing for background completions. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** MSS M1.2: when the caller has already minted an AgentUri (e.g. a
    *  parent spawn pre-allocating ids for tracing), pass it here.
    *  Otherwise registry.spawn mints one. */

package/src/agent-mission/mission-cli.ts

@@ -6,6 +6,7 @@
 
 import { readFileSync } from 'node:fs';
 import type { AgentBackend, AgentMissionResult, EvidenceMode } from './driver.js';
+import type { AgentCliDetection } from './tool-install.js';
 import { buildAgentMissionDevSpec, executeAgentMissionReroute, type runDevPipeline } from '../self-dev/dev-pipeline.js';
 import { parsePositiveInt } from '../self-dev/dev-cli.js';
 import { parsePluginRef } from './in-agent-plugin.js';
@@ -33,6 +34,8 @@ export interface MissionCliOpts {
 
 export interface MissionCliDeps {
   resolveBackend: (name?: string) => AgentBackend;
+  detectAgentCli?: (agent: 'claude' | 'codex') => AgentCliDetection;
+  onStatus?: (line: string) => void;
   signal?: AbortSignal;
   readFile?: (path: string) => string;
   runDevPipeline?: typeof runDevPipeline;
@@ -114,6 +117,27 @@ export async function runAgentMissionCliCommand(
     ...(opts.deliverable ? { deliverableHint: opts.deliverable } : {}),
     ...(opts.screens ? { screensDir: opts.screens } : {}),
   });
+  // The production CLI injects the host probe; injected tests can assert this preflight
+  // without spawning an agent CLI. For a chain, inspect each external CLI before any launch.
+  const externalAgents = [...new Set((chain ?? [agentBackend.name]).filter(
+    (name): name is 'claude' | 'codex' => name === 'claude' || name === 'codex',
+  ))];
+  const detections = deps.detectAgentCli ? externalAgents.map((agent) => deps.detectAgentCli!(agent)) : [];
+  const statusLine = detections.map(({ message }) => message).join(' · ');
+  if (statusLine) deps.onStatus?.(statusLine);
+  const notReady = detections.find(({ installed, login }) => installed !== true || login !== 'ready');
+  if (notReady) {
+    const message = notReady.installed === false
+      ? `${notReady.message}; 공식 설치 후 다시 실행`
+      : notReady.installed === null
+        ? `${notReady.message}; 설치 상태를 확인한 뒤 다시 실행`
+        : notReady.login === 'api-key'
+          ? `${notReady.message}; API 키 요금 고지와 동의 화면이 아직 없어 미션을 시작하지 않습니다 — Codex 구독 로그인(codex login) 후 다시 실행`
+        : notReady.login === 'needed'
+          ? `${notReady.message}; ${notReady.agent} login 후 다시 실행`
+          : `${notReady.message}; 로그인 상태를 확인한 뒤 다시 실행`;
+    return { ok: false, message, exitCode: 1 };
+  }
   const { result, exitCode } = await executeAgentMissionReroute(
     spec, agentBackend,
     { ...(deps.runDevPipeline ? { runDevPipeline: deps.runDevPipeline } : {}), ...(deps.signal ? { signal: deps.signal } : {}) },