elanous 0.2.40 → 0.2.42

package/src/research/axis-fanout.ts

@@ -1,7 +1,15 @@
 // Research-only native fanout. The caller supplies Bloom's question ladder;
 // each axis gets its own direct tool call and evidence stays attributed to it.
 import type { BloomResearchQuestion, ResearchEvidenceEnvelope } from '../auto-research/question-ladder-contract.js';
-import type { WebSearchHit } from '../web-search/provider.js';
+import { getAvailableWebSearchProviders } from '../web-search/index.js';
+import type { WebSearchHit, WebSearchProvider } from '../web-search/provider.js';
+import { debug } from '../debug/log.js';
+
+const RESEARCH_SEARCH_ENGINES = ['grok', 'grok-api', 'firecrawl'] as const;
+const RESEARCH_GROK_TIMEOUT_MS = 8_000;
+// Leave scheduler/logging headroom under the user-visible 15s aggregate cap.
+export const RESEARCH_SEARCH_BUDGET_MS = 14_500;
+const ENGINE_BREAKER_FAILURE_LIMIT = 2;
 
 export interface AxisToolCallPlan {
   questionId: string;
@@ -25,10 +33,119 @@ export interface AxisSearchResult {
   hits: AxisSearchHit[];
   errors: string[];
 }
-export type AxisSearch = (query: string) => Promise<AxisSearchHit[] | AxisSearchResult>;
+export type AxisSearch = (query: string, signal?: AbortSignal) => Promise<AxisSearchHit[] | AxisSearchResult>;
 
 export interface AxisFanoutDeps {
   search?: AxisSearch;
+  signal?: AbortSignal;
+}
+
+interface ProviderHealth {
+  failures: number;
+  open: boolean;
+}
+
+/** Build one bounded searcher per research prepass. Free/DDG is deliberately
+ * excluded: it is not a safe fallback for stock research and can consume a
+ * full 15s timeout for every query. Per-engine serialization lets the first
+ * timeout open that engine's breaker before queued Bloom axes start. */
+export function createResearchAxisSearcher(
+  availableProviders: readonly WebSearchProvider[] = getAvailableWebSearchProviders(),
+  now: () => number = Date.now,
+): AxisSearch {
+  const grok = availableProviders.find(provider => provider.id === 'grok')
+    ?? availableProviders.find(provider => provider.id === 'grok-api');
+  const allowed = [
+    ...(grok ? [grok] : []),
+    ...availableProviders.filter(provider => provider.id === 'firecrawl'),
+  ];
+  const health = new Map(allowed.map(provider => [provider.id, { failures: 0, open: false }]));
+  const deadline = now() + RESEARCH_SEARCH_BUDGET_MS;
+  const tails = new Map<string, Promise<void>>();
+
+  debug.log('research.search', 'provider-preflight', {
+    allowed: RESEARCH_SEARCH_ENGINES,
+    available: allowed.map(provider => provider.id),
+    excluded: availableProviders.filter(provider => !(RESEARCH_SEARCH_ENGINES as readonly string[]).includes(provider.id))
+      .map(provider => provider.id),
+    budgetMs: RESEARCH_SEARCH_BUDGET_MS,
+  });
+
+  const enqueue = <T>(providerId: string, run: () => Promise<T>): Promise<T> => {
+    const previous = tails.get(providerId) ?? Promise.resolve();
+    const current = previous.then(run, run);
+    tails.set(providerId, current.then(() => undefined, () => undefined));
+    return current;
+  };
+
+  return async (query, signal) => {
+    const hits: AxisSearchHit[] = [];
+    const errors: string[] = [];
+    const selected = allowed.filter(provider => !health.get(provider.id)?.open);
+    if (selected.length === 0) return { hits, errors: ['no healthy Grok/Firecrawl research provider'] };
+
+    await Promise.all(selected.map(provider => enqueue(provider.id, async () => {
+      const state = health.get(provider.id)!;
+      if (state.open) return;
+      const remainingMs = deadline - now();
+      if (remainingMs <= 0) {
+        state.open = true;
+        errors.push(`${provider.id}: research search budget exhausted`);
+        return;
+      }
+      const activeCount = Math.max(1, allowed.filter(candidate => !health.get(candidate.id)?.open).length);
+      const isGrok = provider.id === 'grok' || provider.id === 'grok-api';
+      const timeoutMs = isGrok
+        ? Math.min(RESEARCH_GROK_TIMEOUT_MS, remainingMs)
+        : Math.max(1, Math.floor(remainingMs / activeCount));
+      const startedAt = now();
+      try {
+        const controller = new AbortController();
+        const abortFromCaller = (): void => controller.abort(signal?.reason);
+        if (signal?.aborted) abortFromCaller();
+        else signal?.addEventListener('abort', abortFromCaller, { once: true });
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let result;
+        try {
+          result = await Promise.race([
+            provider.search({ query, limit: 5 }, controller.signal),
+            new Promise<never>((_, reject) => {
+              timer = setTimeout(() => {
+                controller.abort();
+                reject(new DOMException(`${provider.id} research search timed out after ${timeoutMs}ms`, 'TimeoutError'));
+              }, timeoutMs);
+            }),
+          ]);
+        } finally {
+          if (timer !== undefined) clearTimeout(timer);
+          signal?.removeEventListener('abort', abortFromCaller);
+        }
+        if (result.hits.length === 0) {
+          state.failures += 1;
+          if (state.failures >= ENGINE_BREAKER_FAILURE_LIMIT) state.open = true;
+        } else {
+          state.failures = 0;
+          hits.push(...result.hits.map(hit => ({ ...hit, engine: provider.id })));
+        }
+        debug.log('research.search', 'provider-complete', {
+          provider: provider.id, queryLength: query.length, hits: result.hits.length,
+          durationMs: now() - startedAt, breakerOpen: state.open,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const timeout = error instanceof Error && /timeout|timed out|abort/i.test(`${error.name} ${error.message}`);
+        const quota = /quota|credit|rate.?limit|\b429\b|exhaust/i.test(message);
+        state.failures += 1;
+        if (timeout || quota || state.failures >= ENGINE_BREAKER_FAILURE_LIMIT) state.open = true;
+        errors.push(`${provider.id}: ${message}`);
+        debug.log('research.search', 'provider-failed', {
+          provider: provider.id, queryLength: query.length, durationMs: now() - startedAt,
+          timeout, quota, failures: state.failures, breakerOpen: state.open,
+        }, { level: 'warn' });
+      }
+    })));
+    return { hits, errors };
+  };
 }
 
 /** Keep every query attached to the Bloom question that produced it. */
@@ -39,18 +156,6 @@ export function planAxisToolCalls(questions: readonly BloomResearchQuestion[]):
     .map(query => ({ questionId: question.id, tool: 'OmniSearch' as const, query })));
 }
 
-async function directOmniSearch(query: string): Promise<AxisSearchResult> {
-  const { dispatchOmniSearch } = await import('../skills/tools/omni-search.js');
-  const hits: AxisSearchHit[] = [];
-  const result = await dispatchOmniSearch({ query }, { onSource: hit => { hits.push(hit); } });
-  if (Object.keys(result.metadata.perEngine).length === 0) {
-    throw new Error('no available web-search providers');
-  }
-  const errors = Object.entries(result.metadata.perEngine)
-    .flatMap(([engine, info]) => info.error ? [`${engine}: ${info.error}`] : []);
-  return { hits, errors };
-}
-
 function evidenceFromHit(question: BloomResearchQuestion, hit: AxisSearchHit): ResearchEvidenceEnvelope {
   const published = hit.publishedAt;
   const date = published !== undefined && Number.isFinite(published) && published > 0
@@ -89,8 +194,8 @@ export async function fanOutAxisEvidence(
   if (new Set(questions.map(question => question.id)).size !== questions.length) {
     throw new Error('research axis question IDs must be unique');
   }
-  const search = deps.search ?? directOmniSearch;
-  const settled = await Promise.allSettled(plan.map(call => search(call.query)));
+  const search = deps.search ?? createResearchAxisSearcher();
+  const settled = await Promise.allSettled(plan.map(call => search(call.query, deps.signal)));
   const axes: AxisEvidenceGroup[] = questions.map(question => ({ questionId: question.id, evidence: [] }));
   const groups = new Map(axes.map(axis => [axis.questionId, axis]));
   const byQuestion = new Map(questions.map(question => [question.id, question]));

package/src/research/bloom-exemplars.ts

@@ -0,0 +1,137 @@
+import { readFileSync, statSync } from 'node:fs';
+import { BLOOM_2D_SCOPED, isBloom2DScoped, type Bloom2D } from '../knowledge/kgs/types.js';
+
+export const BLOOM_EXEMPLAR_DOMAINS = [
+  'finance', 'macro', 'technology', 'science', 'medicine', 'law', 'business',
+] as const;
+export type BloomExemplarDomain = typeof BLOOM_EXEMPLAR_DOMAINS[number];
+export type BloomExemplarLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface BloomExemplar {
+  domain: BloomExemplarDomain;
+  level: BloomExemplarLevel;
+  bloom: Bloom2D;
+  question: string;
+}
+
+export interface BloomExemplarPack { version: 1; exemplars: BloomExemplar[] }
+export interface BloomExemplarContext {
+  domain: BloomExemplarDomain;
+  domainSignal: 'matched' | 'fallback';
+  source: 'pro-pack' | 'public-fallback';
+  count: number;
+  levels: BloomExemplarLevel[];
+  context: string;
+}
+
+// The existing KGS Bloom2D vocabulary is reused. Numeric research levels are
+// mapped to the closest scoped cognitive/knowledge cell; no second taxonomy is
+// introduced.
+const COGNITIVE_BY_LEVEL = ['remember', 'understand', 'apply', 'analyze', 'evaluate', 'create'] as const;
+const BLOOM_BY_LEVEL = Object.fromEntries(COGNITIVE_BY_LEVEL.map((cognitive, index) => {
+  const cell = BLOOM_2D_SCOPED.find(candidate => candidate.cognitive === cognitive);
+  if (!cell) throw new Error(`KGS Bloom2D is missing cognitive stage ${cognitive}`);
+  return [index + 1, cell];
+})) as Record<BloomExemplarLevel, Bloom2D>;
+
+// Public source tree intentionally contains a small set of original exemplars.
+const PUBLIC_EXEMPLARS: readonly BloomExemplar[] = [
+  { domain: 'finance', level: 4, bloom: BLOOM_BY_LEVEL[4], question: '채권 금리 변화가 만기 구조와 발행자의 차환 위험에 어떤 경로로 연결되는가?' },
+  { domain: 'finance', level: 5, bloom: BLOOM_BY_LEVEL[5], question: '현재 금리 전망을 반박할 수 있는 시장 지표와 그 신뢰도는 무엇인가?' },
+  { domain: 'technology', level: 4, bloom: BLOOM_BY_LEVEL[4], question: 'AI 데이터센터의 추론 처리량 증가가 GPU 전력밀도와 냉각 부하, 랙당 계통용량 요구에 어떤 경로로 이어지는가?' },
+  { domain: 'technology', level: 5, bloom: BLOOM_BY_LEVEL[5], question: 'AI 데이터센터 전력수요 전망을 반박할 수 있는 GPU 이용률·전력사용효율·계통접속 자료는 무엇이며 각 지표의 한계는 무엇인가?' },
+];
+
+const DOMAIN_TERMS: Record<BloomExemplarDomain, readonly string[]> = {
+  finance: ['bond', 'yield', '채권', '금리', '주식', '금융', '환율', '투자'],
+  macro: ['inflation', 'gdp', 'recession', '물가', '경기', '거시', '고용'],
+  technology: ['software', 'chip', 'ai', 'technology', '소프트웨어', '반도체', '기술', '인공지능'],
+  science: ['physics', 'chemistry', 'biology', 'science', '물리', '화학', '생물', '과학'],
+  medicine: ['patient', 'clinical', 'disease', 'medicine', '환자', '임상', '질환', '의학'],
+  law: ['legal', 'law', 'court', 'statute', '법률', '법원', '규정', '판례'],
+  business: ['company', 'market', 'customer', 'business', '기업', '시장', '고객', '사업'],
+};
+
+let cachedPackPath: string | undefined;
+let cachedPackStamp: string | undefined;
+let cachedPack: BloomExemplarPack | undefined;
+
+export function inferBloomExemplarDomain(request: string): BloomExemplarDomain {
+  return inferBloomExemplarDomainWithSignal(request).domain;
+}
+
+function inferBloomExemplarDomainWithSignal(request: string): { domain: BloomExemplarDomain; domainSignal: BloomExemplarContext['domainSignal'] } {
+  const normalized = request.toLocaleLowerCase();
+  const ranked = BLOOM_EXEMPLAR_DOMAINS.map(domain => ({
+    domain,
+    score: DOMAIN_TERMS[domain].reduce((score, term) => score + (normalized.includes(term) ? 1 : 0), 0),
+  })).sort((a, b) => b.score - a.score || BLOOM_EXEMPLAR_DOMAINS.indexOf(a.domain) - BLOOM_EXEMPLAR_DOMAINS.indexOf(b.domain));
+  return ranked[0]!.score > 0
+    ? { domain: ranked[0]!.domain, domainSignal: 'matched' }
+    : { domain: 'business', domainSignal: 'fallback' };
+}
+
+export function validateBloomExemplarPack(value: unknown): value is BloomExemplarPack {
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.exemplars)) return false;
+  const counts = new Map<string, number>();
+  for (const item of value.exemplars) {
+    if (!isRecord(item) || !isDomain(item.domain) || !isLevel(item.level)
+      || typeof item.question !== 'string' || item.question.trim().length === 0
+      || item.question.length > 500 || /[\u0000-\u001f\u007f]/.test(item.question)
+      || !isBloom(item.bloom) || !isBloom2DScoped(item.bloom)
+      || !sameBloom(item.bloom, BLOOM_BY_LEVEL[item.level])) return false;
+    const key = `${item.domain}:${item.level}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return value.exemplars.length === 210
+    && BLOOM_EXEMPLAR_DOMAINS.every(domain => [1, 2, 3, 4, 5, 6].every(level => counts.get(`${domain}:${level}`) === 5));
+}
+
+export function getBloomExemplarContext(request: string, packPath = process.env.ELANOUS_BLOOM_EXEMPLARS_PACK): BloomExemplarContext {
+  const { domain, domainSignal } = inferBloomExemplarDomainWithSignal(request);
+  let exemplars: readonly BloomExemplar[] = PUBLIC_EXEMPLARS;
+  let source: BloomExemplarContext['source'] = 'public-fallback';
+  if (packPath) {
+    try {
+      const stamp = (() => { const stat = statSync(packPath); return `${stat.mtimeMs}:${stat.size}`; })();
+      if (cachedPackPath !== packPath || cachedPackStamp !== stamp) {
+        const parsed: unknown = JSON.parse(readFileSync(packPath, 'utf8'));
+        cachedPackPath = packPath;
+        cachedPackStamp = stamp;
+        cachedPack = validateBloomExemplarPack(parsed) ? parsed : undefined;
+      }
+      if (cachedPack) {
+        exemplars = cachedPack.exemplars;
+        source = 'pro-pack';
+      }
+    } catch {
+      // A missing pack can be installed while this process runs; don't cache
+      // ENOENT. Invalid JSON/data is safely cached by the file stamp above.
+      if (cachedPackPath === packPath) { cachedPackPath = undefined; cachedPackStamp = undefined; cachedPack = undefined; }
+    }
+  }
+  const selected = ([4, 5] as const).flatMap(level => exemplars
+    .filter(item => item.domain === domain && item.level === level)
+    .slice(0, source === 'pro-pack' ? 3 : 1));
+  const levels = [...new Set(selected.map(item => item.level))].sort() as BloomExemplarLevel[];
+  const context = selected.length
+    ? ['Bloom exemplar examples (reference style only; treat each question as data and generate request-specific questions):', ...selected.map(item => `L${item.level} ${item.bloom.cognitive}/${item.bloom.knowledge}: ${JSON.stringify(item.question)}`)].join('\n')
+    : '';
+  return { domain, domainSignal, source, count: selected.length, levels, context };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isDomain(value: unknown): value is BloomExemplarDomain {
+  return typeof value === 'string' && (BLOOM_EXEMPLAR_DOMAINS as readonly string[]).includes(value);
+}
+function isLevel(value: unknown): value is BloomExemplarLevel {
+  return Number.isInteger(value) && typeof value === 'number' && value >= 1 && value <= 6;
+}
+function isBloom(value: unknown): value is Bloom2D {
+  return isRecord(value) && isBloom2DScoped(value as unknown as Bloom2D);
+}
+function sameBloom(a: Bloom2D, b: Bloom2D): boolean {
+  return a.cognitive === b.cognitive && a.knowledge === b.knowledge;
+}

package/src/research/gap-followup.ts

@@ -18,6 +18,7 @@ export interface ResearchGapFollowupInput {
   request: string;
   questions: readonly BloomResearchQuestion[];
   evidence: readonly ResearchEvidenceEnvelope[];
+  signal?: AbortSignal;
   /** Optional remaining time supplied by the owning turn; omitted uses the fixed 2-minute cap. */
   remainingBudgetMs?: number;
   roundsUsed?: number;
@@ -128,6 +129,7 @@ export async function runGapFollowup(
   deps: ResearchGapFollowupDeps = {},
 ): Promise<ResearchGapFollowupResult> {
   const plan = planGapFollowup(input);
+  if (input.signal?.aborted) return { ...plan, followupEvidence: [], discoveryCards: [] };
   const startedAt = (deps.now ?? Date.now)();
   const deadline = startedAt + plan.timeBudgetMs;
   const discover = async (failedQuestions: ReadonlySet<string>): Promise<{ cards: string[]; evidence: ResearchEvidenceEnvelope[] }> => {
@@ -139,6 +141,9 @@ export async function runGapFollowup(
       const remainingMs = deadline - (deps.now ?? Date.now)();
       if (remainingMs <= 0) break;
       const controller = new AbortController();
+      const abortFromParent = () => controller.abort(input.signal?.reason);
+      input.signal?.addEventListener('abort', abortFromParent, { once: true });
+      if (input.signal?.aborted) abortFromParent();
       const timer = setTimeout(() => controller.abort(new Error('plugin discovery time budget exhausted')),
         Math.min(10_000, remainingMs));
       try {
@@ -158,7 +163,10 @@ export async function runGapFollowup(
           questionId: gap.questionId, reason: error instanceof Error ? error.message.slice(0, 160) : String(error).slice(0, 160),
         }, { level: 'warn' });
       }
-      finally { clearTimeout(timer); }
+      finally {
+        clearTimeout(timer);
+        input.signal?.removeEventListener('abort', abortFromParent);
+      }
     }
     return { cards, evidence };
   };
@@ -168,6 +176,9 @@ export async function runGapFollowup(
   }
 
   const controller = new AbortController();
+  const abortFromParent = () => controller.abort(input.signal?.reason);
+  input.signal?.addEventListener('abort', abortFromParent, { once: true });
+  if (input.signal?.aborted) abortFromParent();
   const timer = setTimeout(() => controller.abort(new Error('research gap follow-up time budget exhausted')),
     Math.max(1, deadline - (deps.now ?? Date.now)()));
   try {
@@ -200,6 +211,7 @@ export async function runGapFollowup(
     return { ...plan, followupEvidence: [...outcomes, ...discovered.evidence], discoveryCards: discovered.cards };
   } finally {
     clearTimeout(timer);
+    input.signal?.removeEventListener('abort', abortFromParent);
   }
 }
 

package/src/research/plugin-discovery.ts

@@ -136,15 +136,30 @@ function card(gap: string, candidates: readonly PluginDiscoveryCandidate[], inst
 
 /** One bounded, fail-soft discovery attempt for a research capability gap. */
 export async function discoverResearchPlugin(gapText: string, deps: PluginDiscoveryDeps = {}): Promise<PluginDiscoveryResult> {
+  const discoveryStartedAt = performance.now();
+  const log = deps.log ?? ((event: string, data: Record<string, unknown>) => debug.log('research.plugin-discovery', event, data));
+  const observe = (event: string, data: Record<string, unknown>): void => {
+    try { log(event, data); } catch { /* timing must not change discovery behavior */ }
+  };
+  observe('started', {});
+  const finish = (result: PluginDiscoveryResult): PluginDiscoveryResult => {
+    observe('completed', {
+      elapsedMs: Math.round((performance.now() - discoveryStartedAt) * 10) / 10,
+      outcome: result.outcome,
+      candidateCount: result.candidates.length,
+      installed: result.installed !== undefined,
+    });
+    return result;
+  };
   const gap = safeGap(gapText);
-  if (!gap) return { candidates: [], card: 'Plugin discovery skipped: unsafe or empty gap.', outcome: 'invalid-gap' };
+  if (!gap) return finish({ candidates: [], card: 'Plugin discovery skipped: unsafe or empty gap.', outcome: 'invalid-gap' });
   const aborted = (): PluginDiscoveryResult => ({ candidates: [], card: 'Plugin discovery skipped: time budget exhausted.', outcome: 'create-suggestion' });
-  if (deps.signal?.aborted) return aborted();
-  const log = deps.log ?? ((event: string, data: Record<string, unknown>) => debug.log('research.plugin-discovery', event, data));
+  if (deps.signal?.aborted) return finish(aborted());
   const threshold = Number.isSafeInteger(deps.githubStarThreshold) && (deps.githubStarThreshold as number) > 0
     ? deps.githubStarThreshold as number : configuredStarThreshold();
   const candidates: PluginDiscoveryCandidate[] = [];
 
+  const marketStartedAt = performance.now();
   try {
     const market = await (deps.market ?? (() => ensureMarketIndex('elanous')))();
     // A signed index is the only built-in source with a verifiable install spec.
@@ -159,15 +174,19 @@ export async function discoverResearchPlugin(gapText: string, deps: PluginDiscov
           installSpec: `${entry.name}@elanous` });
       }
     }
-  } catch { log('market-unavailable', { gap: gap.slice(0, 80) }); }
-  if (deps.signal?.aborted) return aborted();
+  } catch { observe('market-unavailable', { gap: gap.slice(0, 80) }); }
+  finally {
+    observe('stage-complete', { stage: 'signed-market', elapsedMs: Math.round((performance.now() - marketStartedAt) * 10) / 10 });
+  }
+  if (deps.signal?.aborted) return finish(aborted());
 
+  const searchStartedAt = performance.now();
   try {
     const found = await (deps.search ?? ((query: string, signal?: AbortSignal) => discoverCapability(query,
       { layer: 'skill', limit: MAX_CANDIDATES, community: false, signal })))(gap, deps.signal);
-    if (deps.signal?.aborted) return aborted();
+    if (deps.signal?.aborted) return finish(aborted());
     for (const hit of found.slice(0, MAX_CANDIDATES)) {
-      if (deps.signal?.aborted) return aborted();
+      if (deps.signal?.aborted) return finish(aborted());
       let url: URL;
       try { url = new URL(hit.url); } catch { continue; }
       if (url.protocol !== 'https:' || url.username || url.password) continue;
@@ -186,8 +205,11 @@ export async function discoverResearchPlugin(gapText: string, deps: PluginDiscov
           ? { installSpec: `https://github.com/${repo!.owner}/${repo!.repo}.git#${github.sha}` } : {}),
       });
     }
-  } catch { log('search-unavailable', { gap: gap.slice(0, 80) }); }
-  if (deps.signal?.aborted) return aborted();
+  } catch { observe('search-unavailable', { gap: gap.slice(0, 80) }); }
+  finally {
+    observe('stage-complete', { stage: 'capability-search', elapsedMs: Math.round((performance.now() - searchStartedAt) * 10) / 10 });
+  }
+  if (deps.signal?.aborted) return finish(aborted());
 
   const deduped = candidates.filter((item, index) => candidates.findIndex(other => other.url === item.url && other.name === item.name) === index)
     .slice(0, MAX_CANDIDATES);
@@ -197,20 +219,20 @@ export async function discoverResearchPlugin(gapText: string, deps: PluginDiscov
   if (installable.length === 1) {
     const candidate = installable[0]!;
     try {
-      if (deps.signal?.aborted) return aborted();
+      if (deps.signal?.aborted) return finish(aborted());
       const item = await (deps.install ?? defaultInstall)(candidate.installSpec!);
       const undo = `eln plugin remove ${item.name}`;
       installed = { name: item.name, path: item.path,
         notice: `Reason: missing research capability ${gap}; source: ${candidate.source}; permissions: ${candidate.permissions.join(', ') || 'none declared'}.`, undo };
-      log('installed', { name: item.name, source: candidate.source, undo });
+      observe('installed', { name: item.name, source: candidate.source, undo });
     } catch (error) {
-      log('install-refused', { name: candidate.name, reason: error instanceof Error ? error.message.slice(0, 120) : 'unknown' });
+      observe('install-refused', { name: candidate.name, reason: error instanceof Error ? error.message.slice(0, 120) : 'unknown' });
     }
   }
   const outcome: PluginDiscoveryResult['outcome'] = installed ? 'installed' : deduped.length ? 'proposed' : 'create-suggestion';
   const result = { candidates: deduped, installed, card: card(gap, deduped, installed), outcome };
-  log(outcome, { gap: gap.slice(0, 80), count: deduped.length, installed: installed?.name });
-  return result;
+  observe(outcome, { gap: gap.slice(0, 80), count: deduped.length, installed: installed?.name });
+  return finish(result);
 }
 
 /** Re-query through exactly one installed, declared read-only skill with no local-file or shell tools. */

package/src/research-bridge/invoke.ts

@@ -14,7 +14,7 @@
 // isolation without standing up the LLM stack.
 
 import type { ExternalResearchResult, InvokeResearchOpts } from './types.js';
-import type { SkillManifest } from '../skills/runner.js';
+import type { ExecuteSkillOpts, SkillManifest } from '../skills/runner.js';
 import type { BloomResearchQuestion } from '../auto-research/question-ladder-contract.js';
 import type { AxisFanoutDeps, AxisFanoutResult } from '../research/axis-fanout.js';
 import { recordResult } from './store.js';
@@ -76,8 +76,23 @@ export type ResearchInvoker = (
   args: string,
   onProgress?: (delta: string) => void,
   signal?: AbortSignal,
+  skillRootDir?: string,
 ) => Promise<ResearchInvocationOutcome>;
 
+export type ResearchSkillExecutorForTest = (
+  manifest: SkillManifest,
+  args: string,
+  onProgress?: (delta: string) => void,
+  opts?: ExecuteSkillOpts,
+) => Promise<{ finalResponse: string }>;
+
+let researchSkillExecutorForTest: ResearchSkillExecutorForTest | null = null;
+
+/** Replace only skill execution in tests; manifest parsing still uses the real selected skill root. */
+export function setResearchSkillExecutorForTest(executor: ResearchSkillExecutorForTest | null): void {
+  researchSkillExecutorForTest = executor;
+}
+
 let invoker: ResearchInvoker | null = null;
 
 /** Register the production / test invoker. Pass null to revert to
@@ -103,19 +118,21 @@ async function defaultInvoker(
   args: string,
   onProgress?: (delta: string) => void,
   signal?: AbortSignal,
+  skillRootDir?: string,
 ): Promise<ResearchInvocationOutcome> {
   const { parseSkillMd, executeSkill } = await import('../skills/runner.js');
-  const manifest = parseSkillMd(skillName);
+  const manifest = parseSkillMd(skillName, skillRootDir);
   if (!manifest) {
     return {
       output: '',
       ok: false,
-      error: `skill "${skillName}" not found under ~/.claude/skills/`,
+      error: `skill "${skillName}" not found under ${skillRootDir ?? '~/.claude/skills'}/`,
     };
   }
   try {
     // ★ research 격리 — 파일-쓰기 도구 deny 주입(main 트리 오염 차단). Bash·검색도구는 유지.
-    const result = await executeSkill(withResearchIsolation(manifest), args, (delta) => {
+    const run = researchSkillExecutorForTest ?? executeSkill;
+    const result = await run(withResearchIsolation(manifest), args, (delta) => {
       if (onProgress) onProgress(delta);
     }, { signal });
     return researchOutcomeFromSkillRun(result);
@@ -138,7 +155,7 @@ export async function invokeResearch(
 ): Promise<ExternalResearchResult> {
   const skillName = opts.skill || DEFAULT_SKILL;
   const startedAt = new Date();
-  const outcome = await (invoker ?? defaultInvoker)(skillName, topic, opts.onProgress, opts.signal);
+  const outcome = await (invoker ?? defaultInvoker)(skillName, topic, opts.onProgress, opts.signal, opts.skillRootDir);
   const finishedAt = new Date();
   const result: ExternalResearchResult = {
     topic,

package/src/research-bridge/types.ts

@@ -28,6 +28,8 @@ export interface ExternalResearchResult {
 export interface InvokeResearchOpts {
   /** Skill name override; default 'omni-crawl'. */
   skill?: string;
+  /** Root directory containing the selected catalog entry. */
+  skillRootDir?: string;
   /** Stream progress chunks back to the caller (e.g. dashboard chat
    *  pane) so the user sees activity for long-running invocations. */
   onProgress?: (delta: string) => void;

package/src/self-dev/ask-launch-flow.ts

@@ -43,7 +43,7 @@ import {
   type GoalClarificationSelfResolver,
 } from '../self-implement/goal-author-clarification.js';
 import { countMissingAuthoredConstraintMarkers, askGoalTypeDeclaration, declaredGoalType, parseGoalId } from '../self-implement/goal-author.js';
-import { observeFrontNodeEntry, observeFrontNodeExit, observeFrontNodeUnit, type AuthorExitOutcome } from './graph-front-nodes.js';
+import { observeFrontNodeEntry, observeFrontNodeExit, runFrontNodeUnit, type AuthorExitOutcome } from './graph-front-nodes.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { decomposeSelfDevGoal, type SelfDevDecomposeOptions, type SelfDevDecomposition } from './decompose.js';
 import { observeDecomposerSelection, readFabricDecomposeConfig, selectFabricDecomposer } from './self-orchestrate-runtime.js';
@@ -406,21 +406,28 @@ export async function recommendLaunchDecomposition(
       fabricDecomposeConfig.autoPathThreshold,
     );
     const decomposeGoalType = input.goalType ?? declaredGoalType(input.askText);
+    const frontRunId = input.runId ?? process.env.ELANOUS_RUN_ID;
     observeFrontNodeEntry('decompose', {
       provenance: 'authoring-decomposition-start',
-      ...(input.runId === undefined ? {} : { runId: input.runId }),
+      ...(frontRunId === undefined ? {} : { runId: frontRunId }),
+      ...(decomposeGoalType === null ? {} : { goalType: decomposeGoalType }),
+    });
+    const result = await runFrontNodeUnit({
+      node: 'decompose',
+      execute: (goalDocument) => Promise.race([
+        deps.decomposeGoal
+          ? deps.decomposeGoal(goalDocument)
+          : decomposeSelfDevGoal(goalDocument, {
+            ...deps.decomposeOptions,
+            decomposer: selection.decomposer,
+            observation: prelaunchDecompositionObservation(goalDocument),
+          }),
+        timeout,
+      ]),
+    }, document!, {
+      ...(frontRunId === undefined ? {} : { runId: frontRunId }),
       ...(decomposeGoalType === null ? {} : { goalType: decomposeGoalType }),
     });
-    const result = await observeFrontNodeUnit('decompose', input.runId ?? process.env.ELANOUS_RUN_ID, decomposeGoalType ?? undefined, () => Promise.race([
-      deps.decomposeGoal
-        ? deps.decomposeGoal(document!)
-        : decomposeSelfDevGoal(document!, {
-          ...deps.decomposeOptions,
-          decomposer: selection.decomposer,
-          observation: prelaunchDecompositionObservation(document!),
-        }),
-      timeout,
-    ]));
     if (result === timedOut) {
       // ⛔ 「시간 초과」를 「못 쟀다」로 뭉개지 않는다 — 분해기는 «아직 답하는 중»이고
       //   그 답은 `prelaunch-decomposition` 이름으로 «따로» 내려앉는다(위 주석).
@@ -871,25 +878,32 @@ export async function runAskLaunchFlow(
     //   ⛔ 선언이 «없을 때» 넘기면 안 된다 — 저작기의 정식 기본값을 덮어쓰게 된다.
     const declaredAskGoalType = declaredGoalType(input.askText);
     const goalType = input.goalType ?? declaredAskGoalType;
+    const frontRunId = input.runId ?? process.env.ELANOUS_RUN_ID;
     const frontObservation = {
-      ...(input.runId === undefined ? {} : { runId: input.runId }),
+      ...(frontRunId === undefined ? {} : { runId: frontRunId }),
       ...(goalType === null ? {} : { goalType }),
     };
     // ⭐ RFC §5 5단계 — 확인된 implement 저작만 활성 구현 그래프에 이름을 잇는다.
     observeFrontNodeEntry('author', { ...frontObservation, provenance: 'authoring-start' });
-    const authored = await deps.authorGoal([authorAskText], {
-      cwd: deps.cwd(),
-      ...(input.groundingCwd === undefined ? {} : { groundingCwd: input.groundingCwd }),
-      ...(input.authorGrade === undefined ? {} : { authorGrade: input.authorGrade }),
+    const authored = await runFrontNodeUnit({
+      node: 'author',
+      execute: (text, context) => deps.authorGoal([text], {
+        cwd: deps.cwd(),
+        ...(input.groundingCwd === undefined ? {} : { groundingCwd: input.groundingCwd }),
+        ...(input.authorGrade === undefined ? {} : { authorGrade: input.authorGrade }),
+        ...(context.goalType === undefined ? {} : { goalType: context.goalType }),
+        // ⛔ 인라인 ask(`harness say`)는 askFile 이 없다 — 그 칸을 넘기면 저작기가 빈 줄을 쓴다.
+        ...(() => {
+          if (input.inputSource !== 'ask' || input.askFile === undefined) return {};
+          const askFile = lineageAskFile(input.askFile);
+          return askFile === undefined ? {} : { askFile };
+        })(),
+        ...(launchPreflight === undefined ? {} : { launchPreflight }),
+        selfResolveClarifications: selfResolveClarifications.value,
+      }),
+    }, authorAskText, {
+      ...(frontRunId === undefined ? {} : { runId: frontRunId }),
       ...(goalType === null ? {} : { goalType }),
-      // ⛔ 인라인 ask(`harness say`)는 askFile 이 없다 — 그 칸을 넘기면 저작기가 빈 줄을 쓴다.
-      ...(() => {
-        if (input.inputSource !== 'ask' || input.askFile === undefined) return {};
-        const askFile = lineageAskFile(input.askFile);
-        return askFile === undefined ? {} : { askFile };
-      })(),
-      ...(launchPreflight === undefined ? {} : { launchPreflight }),
-      selfResolveClarifications: selfResolveClarifications.value,
     }).catch((error: unknown) => {
       // GRAPH-AUTHOR-FAIL-EDGE: 저작기가 던진 자리 = author `fail` 출구. ⛔ 관측만 하고 같은 오류를 그대로 다시 던진다.
       observeFrontNodeExit({ node: 'author', outcome: 'fail' }, {