elanous 0.2.36 → 0.2.38

package/src/release-loop/landed-but-yellow.ts

@@ -1,4 +1,6 @@
 import { ownerMatches, type ChecklistItem } from './checklist.js';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 
 export interface MergedChecklistPr { number: number; title: string; body: string | null; mergedAt: string }
 type PrMatchBasis = 'cell-line' | 'title-strong' | 'mention';
@@ -113,35 +115,106 @@ export function landedButYellow(items: readonly ChecklistItem[], prs: readonly M
   return rows.sort((a, b) => Number(b.newer) - Number(a.newer));
 }
 
-export interface MergedPrRunResult { status: number | null; stdout: string; stderr: string }
+export interface MergedPrRunResult { status: number | null; stdout: string; stderr: string; timedOut?: boolean }
 /** One `gh` invocation; resolves when the process exits. */
-export type MergedPrRunner = (command: string, args: readonly string[], cwd: string) => Promise<MergedPrRunResult>;
+export type MergedPrRunner = (command: string, args: readonly string[], cwd: string, timeoutMs?: number) => Promise<MergedPrRunResult>;
 
 export const MERGED_PR_LIMIT = 400;
 /** Concurrent `gh pr list` calls once the first page is full (LANDED-YELLOW-FAST · 10-21 prod: 24 sequential calls ≈ 145s). */
 export const MERGED_PR_CONCURRENCY = 6;
 const DAY_MS = 86_400_000;
 
+export interface MergedChecklistFetch {
+  prs: MergedChecklistPr[];
+  truncated: boolean;
+  calls: number;
+  /** Set when a time budget stopped the window walk before every window was fetched. */
+  stopReason: 'time-budget-exceeded' | undefined;
+  /** UTC windows not yet fetched when `stopReason` is set. */
+  remainingWindows: string[];
+}
+
+const FETCH_CACHE_TTL_MS = 10 * 60_000;
+interface PersistedFetchCache { schema: 1; entries: Record<string, { savedAt: number; result: MergedChecklistFetch }> }
+
+function cacheRead(path: string, key: string, nowMs: number): MergedChecklistFetch | undefined {
+  try {
+    if (!existsSync(path)) return undefined;
+    const cache = JSON.parse(readFileSync(path, 'utf8')) as PersistedFetchCache;
+    const entry = cache?.schema === 1 ? cache.entries?.[key] : undefined;
+    if (!entry || !Number.isFinite(entry.savedAt) || nowMs - entry.savedAt < 0 || nowMs - entry.savedAt >= FETCH_CACHE_TTL_MS) return undefined;
+    if (!Array.isArray(entry.result?.prs) || entry.result.stopReason !== undefined) return undefined;
+    return { ...entry.result, calls: 0 };
+  } catch { return undefined; }
+}
+
+function cacheWrite(path: string, key: string, result: MergedChecklistFetch, nowMs: number): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    let entries: PersistedFetchCache['entries'] = {};
+    try {
+      const cache = JSON.parse(readFileSync(path, 'utf8')) as PersistedFetchCache;
+      if (cache?.schema === 1 && cache.entries && typeof cache.entries === 'object') entries = cache.entries;
+    } catch { /* replace an unreadable cache with a fresh one */ }
+    for (const [entryKey, entry] of Object.entries(entries)) if (!Number.isFinite(entry.savedAt) || nowMs - entry.savedAt >= FETCH_CACHE_TTL_MS) delete entries[entryKey];
+    entries[key] = { savedAt: nowMs, result };
+    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ schema: 1, entries } satisfies PersistedFetchCache)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+  } catch { /* cache is an optimization; a failed write must not fail the read-only command */ }
+}
+
 /**
  * Merged PRs since `since` (UTC date). One call answers when it returns fewer than the cap. Otherwise the range
  * splits into UTC-day windows fetched with a concurrency cap; a full window is halved down to one second as before,
  * and a full one-second window probes one extra row to tell exactly 400 from truncation.
+ * With `timeBudgetMs`, each gh request is bounded by the remaining time; a slow initial request or window returns the
+ * partial result with `stopReason: 'time-budget-exceeded'` and UTC window starts in `remainingWindows`.
  * The returned set and the truncation flag match the former sequential bisection; only call shape and time differ.
+ * A completed result is cached across CLI processes for ten minutes; a partial (`stopReason`) result is never cached.
  */
 export async function fetchMergedChecklistPrs(since: string, now: Date, run: MergedPrRunner, cwd: string,
-  { concurrency = MERGED_PR_CONCURRENCY }: { concurrency?: number } = {}): Promise<{ prs: MergedChecklistPr[]; truncated: boolean; calls: number }> {
+  { concurrency = MERGED_PR_CONCURRENCY, timeBudgetMs, cacheFile }: { concurrency?: number; timeBudgetMs?: number; cacheFile?: string } = {}): Promise<MergedChecklistFetch> {
+  const cacheKey = JSON.stringify([since, now.toISOString().slice(0, 10), cwd, concurrency,
+    process.env.GH_REPO ?? process.env.GITHUB_REPOSITORY ?? '']);
+  const cached = cacheFile ? cacheRead(cacheFile, cacheKey, Date.now()) : undefined;
+  if (cached) return cached;
+  const deadline = timeBudgetMs === undefined ? undefined : performance.now() + timeBudgetMs;
+  const over = (): boolean => deadline !== undefined && performance.now() >= deadline;
+  const cacheable = (result: MergedChecklistFetch): MergedChecklistFetch => {
+    if (result.stopReason !== undefined || !cacheFile) return result;
+    cacheWrite(cacheFile, cacheKey, result, Date.now());
+    return result;
+  };
   let calls = 0;
-  const fetch = async (lower: string, upper?: string, limit = MERGED_PR_LIMIT): Promise<MergedChecklistPr[]> => {
+  const fetch = async (lower: string, upper?: string, limit = MERGED_PR_LIMIT): Promise<MergedChecklistPr[] | null> => {
     const search = `merged:>=${lower}${upper ? ` merged:<${upper}` : ''}`;
+    if (over()) return null;
     calls++;
-    const r = await run('gh', ['pr', 'list', '--state', 'merged', '--search', search, '--limit', String(limit), '--json', 'number,title,body,mergedAt'], cwd);
+    const args = ['pr', 'list', '--state', 'merged', '--search', search, '--limit', String(limit), '--json', 'number,title,body,mergedAt'];
+    const remainingMs = deadline === undefined ? undefined : Math.max(1, Math.ceil(deadline - performance.now()));
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const request = run('gh', args, cwd, remainingMs);
+    let r: MergedPrRunResult | null;
+    try {
+      r = remainingMs === undefined ? await request : await Promise.race([
+        request,
+        new Promise<null>((resolve) => { timer = setTimeout(() => resolve(null), remainingMs); }),
+      ]);
+    } finally { if (timer !== undefined) clearTimeout(timer); }
+    if (r === null || r.timedOut) return null;
     if (r.status !== 0) throw new Error(`병합 PR 조회(gh) 실패 rc=${r.status}: ${(r.stderr || r.stdout).trim().slice(0, 400)}`);
     const page = JSON.parse(r.stdout.trim()) as MergedChecklistPr[];
     if (!Array.isArray(page)) throw new Error('병합 PR 조회(gh): 배열이 아니다');
     return page;
   };
+  const lower = Date.parse(`${since}T00:00:00Z`);
+  const upper = Math.max(lower + 1000, Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+  const windows: Array<[number, number]> = [];
+  for (let start = lower; start < upper; start += DAY_MS) windows.push([start, Math.min(start + DAY_MS, upper)]);
   const first = await fetch(since);
-  if (first.length < MERGED_PR_LIMIT) return { prs: first, truncated: false, calls };
+  if (first === null) return cacheable({ prs: [], truncated: false, calls, stopReason: 'time-budget-exceeded', remainingWindows: windows.map(([start]) => new Date(start).toISOString()) });
+  if (first.length < MERGED_PR_LIMIT) return cacheable({ prs: first, truncated: false, calls, stopReason: undefined, remainingWindows: [] });
   // Bounded pool: at most `concurrency` gh processes at once; a failure stops new calls and rejects.
   let active = 0;
   let failed: unknown;
@@ -155,14 +228,20 @@ export async function fetchMergedChecklistPrs(since: string, now: Date, run: Mer
     finally { active--; if (failed !== undefined) for (const wake of waiting.splice(0)) wake(); else waiting.shift()?.(); }
   };
   let truncated = false;
+  const remainingWindows: string[] = [];
   const visit = async (start: number, end: number): Promise<MergedChecklistPr[]> => {
     const from = new Date(start).toISOString();
     const to = new Date(end).toISOString();
-    const page = await limited(() => fetch(from, to));
+    // The budget is checked when the window actually starts (inside the pool), not when `visit` is mapped —
+    // every window is mapped at once, so a check here would run before the first fetch resolves.
+    const page = await limited(async () => (over() ? null : fetch(from, to)));
+    if (page === null) { remainingWindows.push(from); return []; }
     if (page.length < MERGED_PR_LIMIT) return page;
     if (end - start <= 1000) {
       // The second-precision search cannot be subdivided; probe one extra row to distinguish exactly 400 from a real truncation.
+      if (over()) { remainingWindows.push(from); return page.slice(0, MERGED_PR_LIMIT); }
       const probe = await limited(() => fetch(from, to, MERGED_PR_LIMIT + 1));
+      if (probe === null) { remainingWindows.push(from); return page.slice(0, MERGED_PR_LIMIT); }
       if (probe.length > MERGED_PR_LIMIT) truncated = true;
       return probe.slice(0, MERGED_PR_LIMIT);
     }
@@ -170,15 +249,17 @@ export async function fetchMergedChecklistPrs(since: string, now: Date, run: Mer
     const [left, right] = await Promise.all([visit(start, middle), visit(middle, end)]);
     return [...left, ...right];
   };
-  const lower = Date.parse(`${since}T00:00:00Z`);
-  const upper = Math.max(lower + 1000, Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
-  const windows: Array<[number, number]> = [];
-  for (let start = lower; start < upper; start += DAY_MS) windows.push([start, Math.min(start + DAY_MS, upper)]);
   const settled = await Promise.allSettled(windows.map(([start, end]) => visit(start, end)));
   const rejected = settled.find((result): result is PromiseRejectedResult => result.status === 'rejected');
   if (rejected) throw failed ?? rejected.reason;
   // Chronological window order, first occurrence wins — the same de-duplication as before.
   const unique = new Map<number, MergedChecklistPr>();
   for (const result of settled) for (const pr of (result as PromiseFulfilledResult<MergedChecklistPr[]>).value) if (!unique.has(pr.number)) unique.set(pr.number, pr);
-  return { prs: [...unique.values()], truncated, calls };
+  remainingWindows.sort();
+  if (remainingWindows.length) {
+    // The broad first page is usable partial evidence if the detailed window walk runs out of budget.
+    for (const pr of first) if (!unique.has(pr.number)) unique.set(pr.number, pr);
+    truncated = true;
+  }
+  return cacheable({ prs: [...unique.values()], truncated, calls, stopReason: remainingWindows.length ? 'time-budget-exceeded' : undefined, remainingWindows });
 }

package/src/release-loop/light-rc.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { debug } from '../debug/log.js';
-import { runSelfGateCli, type SelfGateCliOptions, type SelfGateCliResult } from '../self-implement/gate-cli.js';
+import { runSelfGateCliAsync, type SelfGateCliOptions, type SelfGateCliResult } from '../self-implement/gate-cli.js';
 import { dispatchHeavyCheck, isValidGateHost, type DispatchDeps, type DispatchOptions } from '../self-implement/gate-remote.js';
 import { latestPublishedPreviousVersion } from '../../scripts/release-loop/unattended-release.js';
 import { baseVersion, isReleaseVersion } from '../../scripts/release-loop/release-version.js';
@@ -29,6 +29,8 @@ export interface LightRcOptions {
   /** Run on this machine (the remote child is re-invoked with it). */
   local?: boolean;
   shards?: number;
+  /** Maximum simultaneously active gate bundles, including per-file RSS samples (default three). */
+  shardConcurrency?: number;
   /** OP FU — pass `--fixed-shard-distribution` to self gate (sorted round-robin into `shards`, no RSS pre-measurement).
    *  Opt-in; absent = the measured planner, unchanged. Also carried to the remote child. */
   fixedShardDistribution?: boolean;
@@ -71,7 +73,7 @@ export interface LightRcDeps {
   git?: (args: string[], cwd: string) => { rc: number | null; stdout: string };
   previousVersion?: (version: string, ledgerRoot?: string) => string;
   readFile?: (path: string) => string | undefined;
-  runGate?: (cwd: string, options: SelfGateCliOptions) => SelfGateCliResult;
+  runGate?: (cwd: string, options: SelfGateCliOptions) => SelfGateCliResult | Promise<SelfGateCliResult>;
   dispatch?: (opts: DispatchOptions, deps?: DispatchDeps) => Promise<number>;
   /** Extra dispatch deps (runner · settings) — tests drive the real dispatch with a fake host. */
   dispatchDeps?: Omit<DispatchDeps, 'write'>;
@@ -175,6 +177,7 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
   if (!isReleaseVersion(version)) throw new Error(`release version must be x.y.z: ${version}`);
   const shards = opts.shards ?? LIGHT_RC_DEFAULT_SHARDS;
   if (!Number.isSafeInteger(shards) || shards < 1) throw new Error(`invalid --shards count: ${opts.shards}`);
+  if (opts.shardConcurrency !== undefined && (!Number.isSafeInteger(opts.shardConcurrency) || opts.shardConcurrency < 1 || opts.shardConcurrency > 4)) throw new Error(`invalid --shard-concurrency: ${opts.shardConcurrency}`);
   if (opts.remote !== undefined && !isValidGateHost(opts.remote)) throw new Error(`invalid --remote host: ${opts.remote}`);
   const log = opts.log ?? ((line: string) => process.stderr.write(`${line}\n`));
   const cwd = repoRoot(deps);
@@ -195,7 +198,7 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
     try {
       const dir = checkout?.dir ?? cwd;
       if (checkout) alwaysInclude = readList(dir);
-      local = (deps.runGate ?? runSelfGateCli)(dir, { base, shards, ...(opts.fixedShardDistribution ? { fixedShardDistribution: true } : {}), alwaysInclude, includeImporterTests: true });
+      local = await (deps.runGate ?? runSelfGateCliAsync)(dir, { base, shards, ...(opts.shardConcurrency !== undefined ? { shardConcurrency: opts.shardConcurrency } : {}), ...(opts.fixedShardDistribution ? { fixedShardDistribution: true } : {}), alwaysInclude, includeImporterTests: true });
       if (opts.rehearsalTui) {
         const command = async (cmd: string, args: string[], tree: string, limitMs?: number) => {
           const run = spawnSync(cmd, args, { cwd: tree, encoding: 'utf8', timeout: limitMs });
@@ -212,7 +215,7 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
     // Keep the self-gate contract: an unavailable remote leaves this release check unmeasured; do not start a heavy gate locally.
     tool: 'self-gate', repo: cwd, installPwa: true, refs: [base], json: true, commit: measuredCommit,
     // The host re-runs this command with --local (and ELANOUS_GATE_REMOTE_CHILD=1), so it never recurses.
-    remoteArgv: (sha) => ['bun', 'bin/elanous.mjs', 'release', 'light-rc', '--version', version, '--base', sha(base), '--head', measuredCommit, '--shards', String(shards), ...(opts.fixedShardDistribution ? ['--fixed-shard-distribution'] : []), '--local', '--json', ...(opts.rehearsalTui ? ['--rehearsal-tui'] : [])],
+    remoteArgv: (sha) => ['bun', 'bin/elanous.mjs', 'release', 'light-rc', '--version', version, '--base', sha(base), '--head', measuredCommit, '--shards', String(shards), ...(opts.shardConcurrency !== undefined ? ['--shard-concurrency', String(opts.shardConcurrency)] : []), ...(opts.fixedShardDistribution ? ['--fixed-shard-distribution'] : []), '--local', '--json', ...(opts.rehearsalTui ? ['--rehearsal-tui'] : [])],
     flags: { remote: opts.local ? undefined : opts.remote ?? true, local: !!opts.local },
     runLocal,
   }, {

package/src/release-loop/rehearsal.ts

@@ -495,7 +495,7 @@ export async function runRehearsalTick(opts: RehearsalOptions = {}, deps: Rehear
               const introducedCount: number | null = stamp.outcome === 'unmeasured' || stamp.outcome === 'error' ? null : hard.introduced.length;
               const preexistingCount: number | null = introducedCount === null ? null : hard.preexisting;
               const totalFailures: number | null = introducedCount === null || preexistingCount === null ? null : introducedCount + preexistingCount;
-              stamp.summary = oneLine(`hard gate ${hard.outcome} · introduced ${introducedCount ?? 'UNKNOWN'} · preexisting ${preexistingCount ?? 'UNKNOWN'} · total failures ${totalFailures ?? 'UNKNOWN'} · node-b Pod · 12 shards · runId ${hardGateRunId} · evidence ${hardGateLog}${cause ? ` · ${cause}` : ''}`);
+              stamp.summary = oneLine(`hard gate ${hard.outcome} · introduced ${introducedCount ?? 'UNKNOWN'} · preexisting ${preexistingCount ?? 'UNKNOWN'} · total failures ${totalFailures ?? 'UNKNOWN'} · 원격 Pod · 12 shards · runId ${hardGateRunId} · evidence ${hardGateLog}${cause ? ` · ${cause}` : ''}`);
             } else {
             const shardPlan = opts.shards === undefined ? (deps.shardPlan ?? planRehearsalShards)(plan.version, root, checkout, { ...deps.shardPlanDeps, remoteGate: true }) : undefined;
             if (shardPlan) stamp.shardPlan = shardPlan;

package/src/repl/index.ts

@@ -198,6 +198,7 @@ function buildReplTools(): {
     specs.push(wakeup.spec);
     dispatchByName.set(wakeup.spec.name, wakeup.dispatch);
   }
+  (require('../tui/sidetab/nl-tool.js') as typeof import('../tui/sidetab/nl-tool.js')).registerNextSidetabReplTool(specs, dispatchByName, process as unknown as import('../tui/sidetab/nl-tool.js').NextSidetabIpcProcess);
   const planner = sr.createSearchPlannerState({ maxAutoNarrowCandidates: 2 });
   const dispatch = async (name: string, args: Record<string, unknown>): Promise<unknown> => {
     try {
@@ -211,6 +212,14 @@ function buildReplTools(): {
         searchPlannerState: planner,
         turnIndex: undefined,
         ptyDashboardOn: false,
+        // Match the CLI agent path: native Agent fallback needs the parent's
+        // catalog and dispatcher so children can actually use inherited tools.
+        agentHostTools: specs,
+        agentDispatchTool: dispatch,
+        buildChildToolCatalog: (childCwd: string) => {
+          const cli = require('../cli/agent-cli.js') as typeof import('../cli/agent-cli.js');
+          return cli.buildCliAgentTools(undefined, undefined, childCwd);
+        },
         getToolRuntime: () => undefined,
         dispatchToolRuntime: async (n) => ({ error: `runtime unavailable in REPL: ${n}` }),
         dispatchPluginTool: async (n) => ({ ok: false as const, error: `plugin unavailable in REPL: ${n}` }),
@@ -334,6 +343,7 @@ async function runOneTurn(
   jsonOutput: boolean,
   nextTuiDelivery?: { pending: PendingTaskNotification[] },
   onJsonDelta?: (delta: string) => void,
+  onJsonStatus?: (line: string) => void,
 ): Promise<{ reply: string; provider: string; model: string | null; durationMs: number; logPath: string | null }> {
   const startedAt = Date.now();
   const replyChunks: string[] = [];
@@ -366,6 +376,10 @@ async function runOneTurn(
     userText,
     systemPrompt,
     userImages: userImages.length > 0 ? userImages : undefined,
+    ...(process.env.ELANOUS_TEST_FAKE_LLM === '1' && Number.isFinite(Number(process.env.ELANOUS_TEST_FAKE_LLM_IDLE_TIMEOUT_MS))
+      && Number(process.env.ELANOUS_TEST_FAKE_LLM_IDLE_TIMEOUT_MS) > 0
+      ? { llmOpts: { streamIdleTimeoutMs: Number(process.env.ELANOUS_TEST_FAKE_LLM_IDLE_TIMEOUT_MS) } }
+      : {}),
     onDelta: (d) => {
       if (jsonOutput) {
         replyChunks.push(d);
@@ -373,6 +387,7 @@ async function runOneTurn(
       }
       else process.stdout.write(d);
     },
+    onStatusLine: (line) => { onJsonStatus?.(line); },
     tools: replToolSpecs,
     dispatchTool: tools?.dispatch,
     onToolCall: (call) => {
@@ -777,6 +792,9 @@ export async function runRepl(opts: ReplOpts): Promise<number> {
           process.env.ELANOUS_NEXT_TUI_STREAM === '1' && typeof turn.id === 'string'
             ? (delta) => { process.stdout.write(`${JSON.stringify({ event: 'delta', turnId: turn.id, text: delta })}\n`); }
             : undefined,
+          process.env.ELANOUS_NEXT_TUI_STREAM === '1' && typeof turn.id === 'string'
+            ? (text) => { process.stdout.write(`${JSON.stringify({ event: 'status', turnId: turn.id, text })}\n`); }
+            : undefined,
         );
       } catch (error) {
         if (!backgroundBridge) throw error;

package/src/research/axis-fanout.ts

@@ -0,0 +1,133 @@
+// 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';
+
+export interface AxisToolCallPlan {
+  questionId: string;
+  tool: 'OmniSearch';
+  query: string;
+}
+
+export interface AxisEvidenceGroup {
+  questionId: string;
+  evidence: ResearchEvidenceEnvelope[];
+  error?: string;
+}
+
+export interface AxisFanoutResult {
+  plan: AxisToolCallPlan[];
+  axes: AxisEvidenceGroup[];
+}
+
+export type AxisSearchHit = WebSearchHit & { engine?: string };
+export interface AxisSearchResult {
+  hits: AxisSearchHit[];
+  errors: string[];
+}
+export type AxisSearch = (query: string) => Promise<AxisSearchHit[] | AxisSearchResult>;
+
+export interface AxisFanoutDeps {
+  search?: AxisSearch;
+}
+
+/** Keep every query attached to the Bloom question that produced it. */
+export function planAxisToolCalls(questions: readonly BloomResearchQuestion[]): AxisToolCallPlan[] {
+  return questions.flatMap(question => question.searchTerms
+    .map(query => query.trim())
+    .filter(Boolean)
+    .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
+    ? new Date(published) : undefined;
+  const observedAt = date && Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+  return {
+    questionId: question.id,
+    sourceKind: hit.engine ? `web-search:${hit.engine}` : 'web-search',
+    source: hit.url,
+    ...(question.requestedWindow ? { requestedWindow: question.requestedWindow } : {}),
+    ...(observedAt ? { observedAt } : {}),
+    content: [hit.title, hit.snippet].filter(Boolean).join(' — '),
+    outcome: hit.snippet ? 'complete' : 'partial',
+    truncated: true, // Search snippets are excerpts, not the complete source page.
+  };
+}
+
+function failedEvidence(question: BloomResearchQuestion, query: string, message: string): ResearchEvidenceEnvelope {
+  return {
+    questionId: question.id,
+    sourceKind: 'search-query',
+    source: query,
+    ...(question.requestedWindow ? { requestedWindow: question.requestedWindow } : {}),
+    content: message,
+    outcome: 'failed',
+    truncated: false,
+  };
+}
+
+/** Invoke all axis queries concurrently, preserving ladder order and partial failures. */
+export async function fanOutAxisEvidence(
+  questions: readonly BloomResearchQuestion[],
+  deps: AxisFanoutDeps = {},
+): Promise<AxisFanoutResult> {
+  const plan = planAxisToolCalls(questions);
+  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 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]));
+  for (const question of questions) {
+    if (!plan.some(call => call.questionId === question.id)) {
+      const group = groups.get(question.id)!;
+      group.error = 'no search terms';
+      group.evidence.push(failedEvidence(question, question.prompt, group.error));
+    }
+  }
+  settled.forEach((outcome, index) => {
+    const call = plan[index]!;
+    const group = groups.get(call.questionId)!;
+    const question = byQuestion.get(call.questionId)!;
+    if (outcome.status === 'fulfilled') {
+      const response = Array.isArray(outcome.value) ? { hits: outcome.value, errors: [] } : outcome.value;
+      if (response.hits.length === 0 && response.errors.length === 0) {
+        group.evidence.push({ ...failedEvidence(question, call.query, 'no hits returned'), outcome: 'partial' });
+      }
+      for (const hit of response.hits) {
+        try {
+          group.evidence.push(evidenceFromHit(question, hit));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          group.error = group.error ? `${group.error}; ${message}` : message;
+          group.evidence.push(failedEvidence(question, call.query, message));
+        }
+      }
+      for (const message of response.errors) {
+        group.error = group.error ? `${group.error}; ${message}` : message;
+        group.evidence.push(failedEvidence(question, call.query, message));
+      }
+    } else {
+      const message = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+      group.error = group.error ? `${group.error}; ${message}` : message;
+      group.evidence.push(failedEvidence(question, call.query, message));
+    }
+  });
+  return { plan, axes };
+}

package/src/research/edge-decision.ts

@@ -0,0 +1,88 @@
+import type { GraphNodeSpec } from '../self-implement/graph-yaml.js';
+
+/** Opaque Bloom 4/5 output. The hook owns the decision boundary, not analysis policy. */
+export interface BloomEdgeAssessment {
+  gaps: readonly unknown[];
+  contradictions: readonly unknown[];
+  verdicts: readonly unknown[];
+}
+
+export type ResearchEdgeAction = 'add' | 'prune' | 'deepen' | 'stop';
+
+export interface ResearchEdgeProposal {
+  node: GraphNodeSpec;
+  returnTo?: string;
+  reason: string;
+}
+
+export interface ResearchEdgeDecision {
+  action: ResearchEdgeAction;
+  reason: string;
+  evidence: readonly string[];
+  proposal?: ResearchEdgeProposal;
+}
+
+export interface ResolvedResearchEdgeDecision extends ResearchEdgeDecision {
+  provider: string;
+}
+
+export type ResearchEdgeDecisionProvider = (
+  assessment: BloomEdgeAssessment,
+) => ResearchEdgeDecision | Promise<ResearchEdgeDecision>;
+
+export interface ResearchEdgeDecisionRegistry {
+  register(provider: ResearchEdgeDecisionProvider, name?: string): () => void;
+  decide(assessment: BloomEdgeAssessment): Promise<ResolvedResearchEdgeDecision>;
+}
+
+const noOpDecision: ResearchEdgeDecision = {
+  action: 'stop',
+  reason: 'no edge decision provider registered',
+  evidence: [],
+};
+
+/** One registry belongs to one run. With no provider, the graph takes one round and stops. */
+export function createResearchEdgeDecisionRegistry(): ResearchEdgeDecisionRegistry {
+  const providers = new Map<symbol, { name: string; decide: ResearchEdgeDecisionProvider }>();
+  return {
+    register(provider, name = 'registered') {
+      const key = Symbol('research-edge-decision-provider');
+      providers.set(key, { name, decide: provider });
+      return () => { providers.delete(key); };
+    },
+    async decide(assessment) {
+      const provider = [...providers.values()].at(-1);
+      if (!provider) return { ...noOpDecision, provider: 'default-noop' };
+      try {
+        const decision = await provider.decide(assessment);
+        if (!isResearchEdgeDecision(decision)) {
+          return { action: 'stop', reason: 'edge decision provider returned an invalid decision', evidence: [], provider: provider.name };
+        }
+        return { ...decision, evidence: [...decision.evidence], provider: provider.name };
+      } catch (error) {
+        return { action: 'stop', reason: `edge decision provider failed: ${String(error)}`, evidence: [], provider: provider.name };
+      }
+    },
+  };
+}
+
+function isResearchEdgeDecision(value: unknown): value is ResearchEdgeDecision {
+  if (!isRecord(value) || !['add', 'prune', 'deepen', 'stop'].includes(String(value.action))
+    || typeof value.reason !== 'string' || !value.reason.trim()
+    || !Array.isArray(value.evidence) || !value.evidence.every((item) => typeof item === 'string')) {
+    return false;
+  }
+  if (value.action === 'add') return isResearchEdgeProposal(value.proposal);
+  return value.proposal === undefined;
+}
+
+function isResearchEdgeProposal(value: unknown): value is ResearchEdgeProposal {
+  return isRecord(value) && isRecord(value.node) && typeof value.node.nodeId === 'string'
+    && typeof value.node.kind === 'string' && typeof value.node.recipe === 'string'
+    && typeof value.reason === 'string' && value.reason.trim().length > 0
+    && (value.returnTo === undefined || typeof value.returnTo === 'string');
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/research/output-router.ts

@@ -0,0 +1,127 @@
+import type { SkillIndexEntry } from '../skills/index.js';
+import { getSkillIndex } from '../skills/index.js';
+
+export type ResearchQuestionWeight = 'light' | 'medium' | 'heavy';
+export type ResearchOutputFormat = 'text' | 'table' | 'card' | 'web-article' | 'diagram';
+export type ResearchOutputFallbackReason = 'no-matching-skill-in-registry';
+
+export interface ResearchOutputRouteInput {
+  question: string;
+  synthesizedResult: string;
+  weight?: ResearchQuestionWeight;
+  axes?: readonly string[];
+  skills?: readonly SkillIndexEntry[];
+}
+
+export interface ResearchOutputRouteDecision {
+  weight: ResearchQuestionWeight;
+  weightSource: 'caller' | 'estimated';
+  format: ResearchOutputFormat;
+  skillCallPlan?: { skill: string; args: string };
+  fallbackReason?: ResearchOutputFallbackReason;
+  observation: {
+    resultChars: number;
+    axisCount: number;
+    estimatedWeight: ResearchQuestionWeight;
+    selectedSkill?: string;
+    fallback?: ResearchOutputFallbackReason;
+  };
+}
+
+const OUTPUT_FORMAT_SIGNALS: Record<Exclude<ResearchOutputFormat, 'text'>, readonly string[]> = {
+  table: ['comparison table', 'research table', 'data table', 'tabular report', '비교 표', '조사 표'],
+  card: ['knowledge card', 'research card', 'summary card', 'flashcard', '지식 카드', '요약 카드'],
+  'web-article': ['web article', 'web publishing', 'html article', 'article publishing', '웹 아티클'],
+  diagram: ['diagram', '다이어그램', 'visualization', '시각화', 'chart'],
+};
+
+const normalizeMetadata = (value: string): string => value.toLowerCase().replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').trim();
+
+function countAxes(axes: readonly string[] | undefined): number {
+  return new Set((axes ?? []).map((axis) => normalizeMetadata(axis)).filter(Boolean)).size;
+}
+
+export function estimateResearchQuestionWeight(resultChars: number, axisCount: number): ResearchQuestionWeight {
+  if (resultChars >= 4_000 || axisCount >= 4) return 'heavy';
+  if (resultChars >= 1_200 || axisCount >= 2) return 'medium';
+  return 'light';
+}
+
+function chooseFormat(weight: ResearchQuestionWeight, axisCount: number): ResearchOutputFormat {
+  if (weight === 'light') return 'text';
+  if (weight === 'medium') return axisCount >= 2 ? 'table' : 'card';
+  return axisCount >= 4 ? 'diagram' : 'web-article';
+}
+
+function skillScore(format: Exclude<ResearchOutputFormat, 'text'>, skill: SkillIndexEntry): number {
+  const metadata = normalizeMetadata([
+    skill.name,
+    skill.category ?? '',
+    skill.description,
+    ...skill.triggers,
+    ...skill.extractedTriggers,
+  ].join(' '));
+  return OUTPUT_FORMAT_SIGNALS[format].reduce((score, signal) => {
+    const normalizedSignal = normalizeMetadata(signal);
+    return metadata.includes(normalizedSignal) ? score + normalizedSignal.length : score;
+  }, 0);
+}
+
+function findOutputSkill(
+  format: Exclude<ResearchOutputFormat, 'text'>,
+  skills: readonly SkillIndexEntry[],
+): SkillIndexEntry | undefined {
+  return skills
+    .map((skill) => ({ skill, score: skillScore(format, skill) }))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))[0]?.skill;
+}
+
+function buildSkillArgs(question: string, synthesizedResult: string, format: ResearchOutputFormat): string {
+  return [
+    `Format the synthesized research output as ${format}.`,
+    `Question: ${escapeSkillArgument(question)}`,
+    'Research synthesis:',
+    escapeSkillArgument(synthesizedResult),
+  ].join('\n\n');
+}
+
+/** Keep untrusted research text from closing the XML-like prefill argument block. */
+function escapeSkillArgument(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** Deterministic output routing. Weight may be supplied by an upstream axis; otherwise it is inferred from synthesis size and distinct axes. */
+export function routeResearchOutput(input: ResearchOutputRouteInput): ResearchOutputRouteDecision {
+  const resultChars = input.synthesizedResult.length;
+  const axisCount = countAxes(input.axes);
+  const estimatedWeight = estimateResearchQuestionWeight(resultChars, axisCount);
+  const weight = input.weight ?? estimatedWeight;
+  const desiredFormat = chooseFormat(weight, axisCount);
+  const observation = { resultChars, axisCount, estimatedWeight };
+
+  if (desiredFormat === 'text') {
+    return { weight, weightSource: input.weight ? 'caller' : 'estimated', format: 'text', observation };
+  }
+
+  const registry = input.skills ?? getSkillIndex();
+  const selected = findOutputSkill(desiredFormat, registry);
+  if (!selected) {
+    const fallbackReason: ResearchOutputFallbackReason = 'no-matching-skill-in-registry';
+    return {
+      weight,
+      weightSource: input.weight ? 'caller' : 'estimated',
+      format: 'text',
+      fallbackReason,
+      observation: { ...observation, fallback: fallbackReason },
+    };
+  }
+
+  return {
+    weight,
+    weightSource: input.weight ? 'caller' : 'estimated',
+    format: desiredFormat,
+    skillCallPlan: { skill: selected.name, args: buildSkillArgs(input.question, input.synthesizedResult, desiredFormat) },
+    observation: { ...observation, selectedSkill: selected.name },
+  };
+}