elanous 0.2.36 → 0.2.38

package/src/llm-tool-schema.ts

@@ -0,0 +1,55 @@
+/** Convert legacy JSON Schema tuple `items` arrays to the modern
+ * `prefixItems` form used by Grok's OpenAI-compatible tool validator.
+ * Other schema keywords, including min/maxItems and coordinate constraints,
+ * are preserved recursively. */
+export function sanitizeToolSchemaForGrok(schema: unknown): unknown {
+  if (Array.isArray(schema)) return schema.map(sanitizeToolSchemaForGrok);
+  if (!schema || typeof schema !== 'object') return schema;
+
+  const record = schema as Record<string, unknown>;
+  const tupleItems = Array.isArray(record.items) ? record.items : undefined;
+  const hasPrefixItems = Array.isArray(record.prefixItems);
+  const hasAdditionalItems = Object.prototype.hasOwnProperty.call(record, 'additionalItems');
+  const output: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    if (key === 'additionalItems' || (key === 'items' && tupleItems)) continue;
+    output[key] = sanitizeToolSchemaForGrok(value);
+  }
+
+  if (tupleItems) {
+    output.prefixItems = tupleItems.map(sanitizeToolSchemaForGrok);
+  }
+  if (hasAdditionalItems && (tupleItems || hasPrefixItems)) {
+    output.items = sanitizeToolSchemaForGrok(record.additionalItems);
+  }
+
+  return output;
+}
+
+/** Anthropic-backed Claude APIs reject top-level JSON Schema composition on tool inputs.
+ * Check every tool before serialization so a newly introduced tool cannot turn a whole
+ * Claude request into a 400 and trigger an unnoticed provider fallback. Nested schemas
+ * remain valid and are deliberately not inspected here. */
+export function assertNoTopLevelToolSchemaCombinators(
+  tools: readonly { name: string; parameters: unknown }[] | undefined,
+): void {
+  if (!tools?.length) return;
+  const combinators = ['anyOf', 'oneOf', 'allOf'] as const;
+  const invalid = tools.flatMap((tool) => {
+    if (!tool.parameters || typeof tool.parameters !== 'object' || Array.isArray(tool.parameters)) return [];
+    const schema = tool.parameters as Record<string, unknown>;
+    const found = combinators.filter((key) => Object.prototype.hasOwnProperty.call(schema, key));
+    return found.length ? [`${tool.name} (${found.join(', ')})`] : [];
+  });
+  if (invalid.length) {
+    throw new Error(`Claude tool schema has unsupported top-level composition: ${invalid.join('; ')}`);
+  }
+}
+
+/** OpenRouter model ids may include the provider prefix; callers can pass
+ * either the catalog id or the already-normalized wire id. */
+export function isOpenRouterGrokModel(model: string): boolean {
+  const wireModel = model.replace(/^openrouter\//i, '');
+  return /^x-ai\/grok(?:[-/]|$)/i.test(wireModel);
+}

package/src/llm.ts

@@ -3,7 +3,7 @@
 // Auto-routes based on model name prefix, or picks the first available provider.
 
 import { wellFormedLLMMessages } from './llm-wellformed.js';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { testFakeLlmEnabled, testFakeLlmProvider } from './ux-sim/fake-llm.js';
 import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -61,6 +61,8 @@ import { resolveModelAlias } from './intelligence-map/model-alias.js';
 import { BUILTIN_CATALOG, reasoningEffortCeiling as reasoningEffortCeilingOf } from './intelligence-map/model-catalog.js';
 import { inferProviderFromModel as registryInferProviderFromModel } from './registry/normalize.js';
 import { closestMatches } from './tool-name-suggest.js';
+import { createProviderToolNameMap } from './llm-tool-name.js';
+import { assertNoTopLevelToolSchemaCombinators, isOpenRouterGrokModel, sanitizeToolSchemaForGrok } from './llm-tool-schema.js';
 import { undoTurnRuntime } from './tool-runtime/undo-turn-runtime.js';
 import { listSnapshots } from './undo-turn/index.js';
 // Zero-dep spec module (no tool-runtime registry) — safe for this hot path.
@@ -276,6 +278,61 @@ export interface LLMToolSpec {
   parameters: Record<string, unknown>;   // JSONSchema
 }
 
+function toolUseNames(messages: readonly LLMMessage[]): string[] {
+  return messages.flatMap((message) => Array.isArray(message.content)
+    ? message.content.flatMap((block) => block.type === 'tool_use' ? [block.name] : [])
+    : []);
+}
+
+function mapProviderToolNamesInMessages(
+  messages: readonly LLMMessage[],
+  mapName: (name: string) => string,
+): LLMMessage[] {
+  return messages.map((message) => {
+    if (!Array.isArray(message.content)) return message;
+    let changed = false;
+    const content = message.content.map((block) => {
+      if (block.type !== 'tool_use') return block;
+      const name = mapName(block.name);
+      if (name === block.name) return block;
+      changed = true;
+      return { ...block, name };
+    });
+    return changed ? { ...message, content } : message;
+  });
+}
+
+function restoreProviderToolCallNames(
+  events: AsyncIterable<LLMStreamEvent>,
+  mapName: (name: string) => string,
+): AsyncIterableIterator<LLMStreamEvent> {
+  // Forward cancellation directly to the provider iterator. An async
+  // generator wrapper waits for a pending `next()` before servicing
+  // `return()`, which can strand the idle watchdog on a hanging stream.
+  const iterator = events[Symbol.asyncIterator]();
+  const mapped: AsyncIterableIterator<LLMStreamEvent> = {
+    [Symbol.asyncIterator]() { return mapped; },
+    async next(value?: unknown) {
+      const result = await iterator.next(value);
+      if (result.done) return { done: true, value: result.value };
+      const event = result.value;
+      return {
+        done: false,
+        value: event.type === 'tool_call' ? { ...event, name: mapName(event.name) } : event,
+      };
+    },
+    async return(value?: void) {
+      if (iterator.return) return iterator.return(value);
+      return { done: true, value };
+    },
+    async throw(error?: unknown) {
+      if (iterator.throw) return iterator.throw(error);
+      throw error;
+    },
+  };
+  return mapped;
+}
+
 /** Events produced by a streaming provider call. Text deltas arrive
  *  incrementally; tool_call events are emitted as COMPLETE units once
  *  the provider finishes streaming the tool_use block — callers don't
@@ -346,6 +403,9 @@ export type ToolChoice = 'auto' | 'required' | 'none' | { name: string };
 
 export interface LLMOpts {
   model?: string;
+  /** Explicit research surface verdict from the turn router. Relaxes early
+   *  exploration guards while retaining a finite tool-loop hard stop. */
+  researchTurn?: boolean;
   /** Reports the provider and model actually attempted, including fallbacks. */
   onResolvedProvider?(provider: string, model: string): void;
   temperature?: number;
@@ -359,6 +419,8 @@ export interface LLMOpts {
   usageRole?: ModelRole;
   /** Optional per-call metering phase; absent calls keep the existing ledger shape. */
   usagePhase?: string;
+  /** Optional per-call self-dev job kind; absent calls keep the existing ledger shape. */
+  usageJobKind?: string;
   /** Optional streamLLM usage-ledger site override (defaults to "stream-llm"). */
   usageSite?: string;
   /**
@@ -2556,7 +2618,7 @@ export function sanitizeToolSchemaForKimi(schema: unknown): unknown {
   ]));
 }
 
-export function toOpenAITools(tools: LLMToolSpec[] | undefined, kimi = false): any[] | undefined {
+export function toOpenAITools(tools: LLMToolSpec[] | undefined, kimi = false, grokTupleItems = false): any[] | undefined {
   const unique = dedupeToolsByName(tools);
   if (!unique || unique.length === 0) return undefined;
   return unique.map(t => ({
@@ -2565,7 +2627,9 @@ export function toOpenAITools(tools: LLMToolSpec[] | undefined, kimi = false): a
       name: t.name, description: t.description,
       parameters: kimi
         ? sanitizeToolSchemaForKimi(strictifyToolSchema(t.parameters))
-        : strictifyToolSchema(t.parameters),
+        : grokTupleItems
+          ? sanitizeToolSchemaForGrok(strictifyToolSchema(t.parameters))
+          : strictifyToolSchema(t.parameters),
     },
   }));
 }
@@ -4410,6 +4474,7 @@ function explainAndLogFallbackCandidates(
 
 /** 스트림 중 끊김 재시도 상한 — codex `DEFAULT_STREAM_MAX_RETRIES`(5) 와 같은 값. */
 const STREAM_DISCONNECT_MAX_RETRIES = 5;
+const STREAM_IDLE_TIMEOUT_MAX_RETRIES = 1;
 let streamDisconnectRetryDelayMs: (attempt: number) => number = backoffMs;
 
 /** @internal 시험 seam — 재시도 대기(기본 `backoffMs`)를 바꾼다. `undefined` 면 원복. */
@@ -4843,6 +4908,7 @@ export async function streamLLM(
     );
     activeProvider = finalized.provider;
     const activeModel = finalized.model;
+    if (getModelFamily(activeModel) === 'claude') assertNoTopLevelToolSchemaCombinators(opts.tools);
     opts.onResolvedProvider?.(activeProvider.name, activeModel);
     debug.log('llm.router', 'streamLLM', {
       provider: activeProvider.name,
@@ -4868,7 +4934,7 @@ export async function streamLLM(
     if (consumed.ok) {
       if (consumed.usage !== 'unmeasured') {
         try {
-          logAgentTurnUsage(activeModel, consumed.usage, { providerName: activeProvider.name, site: opts.usageSite ?? 'stream-llm', role: opts.usageRole, phase: opts.usagePhase });
+          logAgentTurnUsage(activeModel, consumed.usage, { providerName: activeProvider.name, site: opts.usageSite ?? 'stream-llm', role: opts.usageRole, phase: opts.usagePhase, jobKind: opts.usageJobKind });
         } catch { /* best-effort observation */ }
       }
       debug.log('llm', 'outcome', { provider: activeProvider.name, status: 'ok', kind: 'streamLLM', durationMs: Date.now() - started });
@@ -5057,6 +5123,8 @@ export function resolveDefaultProvider(model?: string): LLMProvider {
 export interface StreamWithToolsHandlers {
   /** Streaming text delta — invoked for every text chunk across all turns. */
   onText(delta: string, fullAcrossTurns: string): void;
+  /** Optional status line for hosts that surface transient stream recovery. */
+  onStatus?(line: string): void;
   /** Dispatch a tool call. Returning undefined/null throws in the loop so
    *  callers should always return a JSON-serializable value (can be an
    *  error object — the model will see it as a tool_result either way).
@@ -7321,6 +7389,16 @@ function resultText(result: unknown): string {
   return '';
 }
 
+/** skill_exec returns structured host metadata, but its model-facing tool result is the answer body. */
+function toolResultContentForCall(toolName: string, result: unknown): string {
+  if (toolName === 'skill_exec' && result && typeof result === 'object'
+    && typeof (result as { output?: unknown }).output === 'string') {
+    if ((result as { ok?: unknown }).ok === false) return JSON.stringify(result);
+    return (result as { output: string }).output;
+  }
+  return typeof result === 'string' ? result : JSON.stringify(result);
+}
+
 function detectExecutionFailure(result: unknown): boolean {
   if (!result || typeof result !== 'object') return false;
   const typed = result as Record<string, unknown>;
@@ -8104,17 +8182,19 @@ export function billingRouteForProvider(provider: string | undefined, model: str
 }
 
 /** Observe usage with optional site/role metadata; a provider-name string remains supported. */
-export function logAgentTurnUsage(model: string, usage: LLMUsage, providerNameOrOptions?: string | { providerName?: string; site?: string; role?: ModelRole; phase?: string }): void {
+export function logAgentTurnUsage(model: string, usage: LLMUsage, providerNameOrOptions?: string | { providerName?: string; site?: string; role?: ModelRole; phase?: string; jobKind?: string }): void {
   try {
     const providerName = typeof providerNameOrOptions === 'string' ? providerNameOrOptions : providerNameOrOptions?.providerName;
     const site = (typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.site) ?? 'agent-turn';
     const role = typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.role;
     const phase = typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.phase;
+    const jobKind = typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.jobKind;
     const billing = billingRouteForProvider(providerName, model);
     debug.log('llm.usage', 'llm-usage', {
       site,
       ...(role !== undefined ? { role } : {}),
       ...(phase !== undefined ? { phase } : {}),
+      ...(jobKind !== undefined ? { jobKind } : {}),
       model,
       ...(usage.provider !== undefined && { provider: usage.provider }),
       // ⭐ `provider` 는 «선 어댑터»(openai/anthropic)다 — 과금 주체는 별칭 칸으로(BACKLOG B10).
@@ -8241,6 +8321,10 @@ function applyCodexBehaviorGuard(
   return enabled;
 }
 
+function orchestrationId(): string {
+  return randomUUID();
+}
+
 export async function streamLLMWithTools(
   messages: LLMMessage[],
   handlers: StreamWithToolsHandlers,
@@ -8261,10 +8345,13 @@ export async function streamLLMWithTools(
   let blockedProviders: ProviderFallbackAttempt[] = [];
   const effectiveModel = activeModel;
   const modelFamily = getModelFamily(effectiveModel);
+  const orchestration = orchestrationId();
+  const followupHardStopStats = { wouldBlock: 0, blocked: 0 };
   // Preserve pre-existing GPT-6 behavior while observing Codex-only sites.
   const codexBehaviorGuards = usesCodexBehaviorGuards(effectiveModel);
   const codexGuardCandidate = codexBehaviorGuards || isGpt6GenerationModel(effectiveModel);
   debug.log('llm.router', 'streamLLMWithTools', {
+    orchestrationId: orchestration,
     provider: provider.name,
     model: effectiveModel,
     modelFamily,
@@ -8339,7 +8426,9 @@ export async function streamLLMWithTools(
   const familyDefaultMaxTurns = resolved === 0 ? Number.POSITIVE_INFINITY : (resolved || baselineForFamily);
   // `let` (not const) — the conditional budget-grant hook (opts.budgetGrant)
   // may extend this mid-loop when a designated multi-round tool is called.
-  let maxTurns = opts.maxTurns ?? familyDefaultMaxTurns;
+  let maxTurns = opts.maxTurns ?? (opts.researchTurn
+    ? Math.min(32, Math.max(16, familyDefaultMaxTurns))
+    : familyDefaultMaxTurns);
   const budgetGrant = opts.budgetGrant;
   // ⭐ Hydration-capable tool list (F2 gap④ · 2026-07-26). The provider tool
   // array used to be `opts.tools`, FIXED for the whole loop. That made
@@ -8358,7 +8447,9 @@ export async function streamLLMWithTools(
   } catch { /* config unreadable — default 비-면제·hot-path 는 config 손상에 안 막힌다 */ }
   const inspectBudgetThreshold = getInspectBudgetThreshold(history, modelFamily, codexInspectExemptFlag);
   const inspectFollowupMode = getInspectFollowupMode(history);
-  const explorationThresholdForTurn = getExplorationThreshold(history, maxTurns, modelFamily);
+  const explorationThresholdForTurn = opts.researchTurn
+    ? Number.POSITIVE_INFINITY
+    : getExplorationThreshold(history, maxTurns, modelFamily);
   const maxTurnsUnbounded = maxTurns === Infinity;
   const familyDefaultMaxTurnsUnbounded = familyDefaultMaxTurns === Infinity;
   const explorationUnbounded = !Number.isFinite(explorationThresholdForTurn);
@@ -8373,6 +8464,7 @@ export async function streamLLMWithTools(
       inspectBudgetThreshold,
       inspectFollowupMode,
       explorationThresholdForTurn,
+      researchTurn: opts.researchTurn === true,
       // ★ Infinity 는 JSON 직렬화 시 null 이 되므로 boolean 으로도 남긴다(관측·제1원칙).
       //   true = 프론티어 면제로 read/search 스트릭 컷 없음(대표 방침 2026-07-17).
       explorationUnbounded,
@@ -8761,7 +8853,7 @@ export async function streamLLMWithTools(
     let turnOpts = buildTurnOpts();
     // reasoning-heavy family(codex/claude/gemini/grok/local)는 침묵 추론 구간이 길어 idle watchdog 를
     // family-aware 로 상향(2026-07-19 goal-exec → 아크4 전-family). fast/mini(gpt·other)만 45s 유지.
-    const streamIdleTimeoutMs = usesLongReasoningIdle(modelFamily, activeProvider.name) ? STREAM_IDLE_TIMEOUT_MS_REASONING : STREAM_IDLE_TIMEOUT_MS;
+    const streamIdleTimeoutMs = opts.streamIdleTimeoutMs ?? (usesLongReasoningIdle(modelFamily, activeProvider.name) ? STREAM_IDLE_TIMEOUT_MS_REASONING : STREAM_IDLE_TIMEOUT_MS);
     // ⚠️ hang 진단(2026-07-17) — codex SSE 스트림이 완료 신호 없이 안 끝나는 케이스 확정용.
     // consume-start 후 consume-end 가 없으면 = for-await(streamChat SSE) hang. lastEvType 로 어느
     // 이벤트 뒤에서 멈추는지(usage/text/tool_call) 특정. 무장할 상한도 남겨 실험 런을 구별한다.
@@ -8777,6 +8869,7 @@ export async function streamLLMWithTools(
     // ⭐ TUI-STREAM-RETRY(2026-10-14 실측) — 200 OK 로 흐르던 스트림이 소켓 끊김으로 죽으면 같은 공급자로
     //   다시 건다(codex `stream_max_retries` 동형). 이 턴에서 받은 tool_call·image 가 있으면 재시도하지 않는다.
     let streamDisconnectRetries = 0;
+    let streamIdleTimeoutRetries = 0;
     let streamEmittedImage = false;
     // 끊긴 조각을 이력(turnText·fullText)에서 «조용히» 되감는다 — 화면엔 지우라고 알리지 않는다
     //   (TUI 의 빈 델타는 «커밋»이다). 이미 보인 글과 겹치는 재시도 본문은 `retryDisplay` 가 막는다.
@@ -8808,6 +8901,9 @@ export async function streamLLMWithTools(
     while (true) {
       let idleTimer: ReturnType<typeof setTimeout> | undefined;
       let step: { idle: true } | { idle: false; r: IteratorResult<LLMStreamEvent, void> };
+      // Validate before entering the provider stream's catch/fallback boundary.
+      // An incompatible request is deterministic and must not be retried elsewhere.
+      if (getModelFamily(activeModel) === 'claude') assertNoTopLevelToolSchemaCombinators(turnOpts.tools);
       try {
         if (!streamIter) {
           const finalized = finalizeStreamingProviderModel(activeProvider, activeModel);
@@ -8821,14 +8917,73 @@ export async function streamLLMWithTools(
             debug.log('llm.request', 'lone-surrogate-fixed', { site: 'tool-loop', provider: activeProvider.name, messages: wf.fixedMessages, strings: wf.fixedStrings }, { level: 'warn' });
             history.splice(0, history.length, ...wf.messages);
           }
-          streamIter = activeProvider.streamChat!(history, turnOpts)[Symbol.asyncIterator]();
+          // Provider function names have a narrower wire alphabet than MCP
+          // names. Keep catalog/history names canonical inside the tool loop,
+          // and translate only this request plus the corresponding response.
+          const nameMap = createProviderToolNameMap([
+            ...(turnOpts.tools ?? []).map((tool) => tool.name),
+            ...toolUseNames(history),
+            ...(turnOpts.toolChoice && typeof turnOpts.toolChoice === 'object'
+              ? [turnOpts.toolChoice.name]
+              : []),
+          ]);
+          const providerOpts: LLMOpts = {
+            ...turnOpts,
+            tools: turnOpts.tools?.map((tool) => ({ ...tool, name: nameMap.toProviderName(tool.name) })),
+            toolChoice: turnOpts.toolChoice && typeof turnOpts.toolChoice === 'object'
+              ? { name: nameMap.toProviderName(turnOpts.toolChoice.name) }
+              : turnOpts.toolChoice,
+          };
+          const providerMessages = mapProviderToolNamesInMessages(history, nameMap.toProviderName);
+          streamIter = restoreProviderToolCallNames(
+            activeProvider.streamChat!(providerMessages, providerOpts),
+            nameMap.toOriginalName,
+          )[Symbol.asyncIterator]();
         }
         step = await Promise.race([
           streamIter.next().then((r) => ({ idle: false as const, r })),
           new Promise<{ idle: true }>((res) => { idleTimer = setTimeout(() => res({ idle: true }), streamIdleTimeoutMs); }),
         ]);
+        if (step.idle) {
+          const error = new Error(`stream idle timeout after ${streamIdleTimeoutMs}ms`);
+          error.name = 'StreamIdleTimeoutError';
+          Object.assign(error, { code: 'ETIMEDOUT' });
+          throw error;
+        }
       } catch (err) {
         if (idleTimer) clearTimeout(idleTimer);
+        if (err instanceof Error && err.name === 'StreamIdleTimeoutError') {
+          debug.log('llm.stream', 'idle-timeout', {
+            turn, evCount, lastEvType, idleMs: streamIdleTimeoutMs,
+            textChars: turnText.length, pendingCalls: pendingCalls.length,
+          }, { level: 'warn' });
+          // A provider async iterator can queue return() behind the pending next().
+          // Detach cleanup so it cannot keep the user turn busy forever.
+          const timedOutIterator = streamIter;
+          if (timedOutIterator?.return) {
+            try { void Promise.resolve(timedOutIterator.return(undefined)).catch(() => {}); } catch { /* fail-soft cleanup */ }
+          }
+          if (streamIdleTimeoutRetries < STREAM_IDLE_TIMEOUT_MAX_RETRIES
+            && pendingCalls.length === 0 && !streamEmittedImage && !opts.signal?.aborted) {
+            streamIdleTimeoutRetries++;
+            debug.log('llm.retry', 'idle-timeout-retry', {
+              provider: activeProvider.name, model: activeModel, turn,
+              attempt: streamIdleTimeoutRetries, maxRetries: STREAM_IDLE_TIMEOUT_MAX_RETRIES,
+              delayMs: 0, statusLine: '스트림 무응답 · 재시도',
+            }, { level: 'warn' });
+            handlers.onStatus?.(`스트림 무응답 · 재시도 ${streamIdleTimeoutRetries}/${STREAM_IDLE_TIMEOUT_MAX_RETRIES}`);
+            rewindDisconnectedStream();
+            streamIter = undefined;
+            continue;
+          }
+          // Once a tool call/image escaped, keep the old behavior: finish this
+          // provider turn and never replay or switch providers around side effects.
+          if (pendingCalls.length > 0 || streamEmittedImage || opts.signal?.aborted) break;
+          if (opts.provider) break; // pinned route preserves the prior partial-text result
+          // The retry's text was already sent to the view; drop it from the
+          // logical result before allowing the normal provider fallback path.
+          if (pendingCalls.length === 0 && !streamEmittedImage) rewindDisconnectedStream();
+        }
         if (err instanceof OverloadFailoverError && !opts.provider) {
           const switched = activeProvider.name === 'openai-codex'
             ? firstAvailableFallbackProvider(attemptedProviders, opts)
@@ -8843,6 +8998,7 @@ export async function streamLLMWithTools(
               status: err.status,
               kind: err.kind,
             }, { level: 'warn' });
+            handlers.onStatus?.(`⚠ 공급자 전환: ${activeProvider.name} → ${switched.name} (${err.kind ?? err.name ?? 'unknown'})`);
             const finalized = finalizeStreamingProviderModel(switched, switched.defaultModel);
             activeProvider = finalized.provider;
             activeModel = finalized.model;
@@ -8853,7 +9009,8 @@ export async function streamLLMWithTools(
             continue;
           }
         }
-        if (evCount > 0 && isStreamDisconnectRetryable(err, pendingCalls.length, streamEmittedImage) && !opts.signal?.aborted) {
+        if (!(err instanceof Error && err.name === 'StreamIdleTimeoutError')
+          && evCount > 0 && isStreamDisconnectRetryable(err, pendingCalls.length, streamEmittedImage) && !opts.signal?.aborted) {
           const retryData = {
             provider: activeProvider.name,
             model: activeModel,
@@ -8922,6 +9079,7 @@ export async function streamLLMWithTools(
           tools: activeTools.map((tool) => tool.name),
           ...(opts.model ? { modelOverrideDropped: opts.model } : {}),
         }, { level: 'warn' });
+        handlers.onStatus?.(`⚠ 공급자 전환: ${activeProvider.name} → ${fallback.name} (${verdict.category})`);
         const finalized = finalizeStreamingProviderModel(fallback, fallback.defaultModel);
         activeProvider = finalized.provider;
         activeModel = finalized.model;
@@ -8934,9 +9092,9 @@ export async function streamLLMWithTools(
       }
       if (idleTimer) clearTimeout(idleTimer);
       if (step.idle) {
-        debug.log('llm.stream', 'idle-timeout', { turn, evCount, lastEvType, idleMs: streamIdleTimeoutMs, textChars: turnText.length, pendingCalls: pendingCalls.length }, { level: 'warn' });
-        try { await streamIter.return?.(undefined); } catch { /* fail-soft — 스트림 정리 실패 무시 */ }
-        break;
+        // The race's idle branch is converted to StreamIdleTimeoutError above.
+        // Keep a fail-closed guard for future changes to this loop.
+        throw new Error('stream idle timeout branch escaped recovery');
       }
       if (step.r.done) break;
       const ev = step.r.value;
@@ -8998,7 +9156,7 @@ export async function streamLLMWithTools(
         // ⭐ 주 에이전트 턴의 토큰·비용을 «게이트 없이» 남긴다(2026-09-24 실측: 이 줄이 없어 3시간 `llm.usage`
         //   18행이 전부 곁가지 두 자리였고, 하니스 런 비용의 거의 전부가 관측 밖이었다). 곁가지와 같은 모양 ·
         //   모르는 모델은 금액 대신 `cost.kind='unknown'`. runId 는 debug.log 가 붙인다. 실패해도 턴은 계속.
-        logAgentTurnUsage(activeModel, ev.usage, { providerName: activeProvider.name, role: opts.usageRole, phase: opts.usagePhase });
+        logAgentTurnUsage(activeModel, ev.usage, { providerName: activeProvider.name, role: opts.usageRole, phase: opts.usagePhase, jobKind: opts.usageJobKind });
         // Wave A1 (2026-05-04) — turn-level cache hit rate forensic.
         // Each provider's usage event carries inputTokens / outputTokens
         // / cacheReadInputTokens (when cache hit). Emit the per-turn
@@ -9388,13 +9546,23 @@ export async function streamLLMWithTools(
       // done, just write the answer" UX which we must not preempt.
       const codexImmediateInspectActionStop = followupInspectActionHeld && followupHardStopEnabled;
       if (followupHardStopHeld) {
-        noteGpt6CodexGuard('followup-hard-stop', effectiveModel,
-          (codexImmediateInspectStop && codexInspectSynthesisGrace <= 0)
+        const followupHardStopBlocked = (codexImmediateInspectStop && codexInspectSynthesisGrace <= 0)
           || (codexImmediateRepairStop && codexRepairActionGrace <= 0)
-          || (codexImmediateInspectActionStop && codexInspectActionGrace <= 0));
+          || (codexImmediateInspectActionStop && codexInspectActionGrace <= 0);
+        noteGpt6CodexGuard('followup-hard-stop', effectiveModel, followupHardStopBlocked);
+        if (isGpt6GenerationModel(effectiveModel)) {
+          followupHardStopStats.wouldBlock++;
+          if (followupHardStopBlocked) followupHardStopStats.blocked++;
+          debug.log('llm.router', 'tool-loop.followup-hard-stop.guard-observed', {
+            orchestrationId: orchestration,
+            guard: 'followup-hard-stop',
+            ...followupHardStopStats,
+          });
+        }
       }
       if (codexImmediateInspectStop && codexInspectSynthesisGrace <= 0) {
         debug.log('llm.router', 'tool-loop.inspect-synthesis-phase.codex-immediate-stop', {
+          orchestrationId: orchestration,
           turn,
           maxTurns,
           autoNarrowedReadCount,
@@ -10188,7 +10356,8 @@ export async function streamLLMWithTools(
           //    rejection without colliding with the auto-narrow path)
           //  - call is in SEARCH_ONLY_TOOLS
           if (
-            dispatchedReadCount === 0
+            !opts.researchTurn
+            && dispatchedReadCount === 0
             && autoNarrowedReadCount === 0
             && searchOnlyTurnStreak >= 3
             && SEARCH_ONLY_TOOLS.has(call.name)
@@ -10965,7 +11134,7 @@ export async function streamLLMWithTools(
           resultBlocks.push({
             type: 'tool_result',
             tool_use_id: call.id,
-            content: typeof result === 'string' ? result : JSON.stringify(result),
+            content: toolResultContentForCall(call.name, result),
             ...(isError ? { isError: true } : {}),
           });
         }
@@ -11144,7 +11313,8 @@ export async function streamLLMWithTools(
     // synthesis attempt. Extended to gemini 2026-05-04 alongside
     // W5-E/W5-F for the same pathology shape.
     if (
-      !forceSynthesisAttempted
+      !opts.researchTurn
+      && !forceSynthesisAttempted
       && noContentReadTurnStreak >= 4
       && (modelFamily === 'gemini'
         || applyCodexBehaviorGuard('force-synthesis', effectiveModel, codexGuardCandidate, true))
@@ -11399,7 +11569,13 @@ function makeOpenAICompatProvider(
         throw new Error(`${name} unavailable: configure apiKey via \`elanous setup\``);
       }
       const activeModel = opts.model || model;
-      const tools = toOpenAITools(opts.tools, name === 'openrouter' && openRouterNeedsKimiToolSchema(openRouterWireModel(activeModel)));
+      if (getModelFamily(activeModel) === 'claude') assertNoTopLevelToolSchemaCombinators(opts.tools);
+      const wireModel = name === 'openrouter' ? openRouterWireModel(activeModel) : activeModel;
+      const tools = toOpenAITools(
+        opts.tools,
+        name === 'openrouter' && openRouterNeedsKimiToolSchema(wireModel),
+        name === 'openrouter' && isOpenRouterGrokModel(wireModel),
+      );
       const deepSeek = name === 'openrouter' && isOpenRouterDeepSeekWireModel(openRouterWireModel(activeModel));
       // OR-TOOLCHOICE-PASS (2026-10-10) — OpenRouter 경로만 호출자 toolChoice 를 싣는다.
       //   ⛔ grok/openai 호환 경로는 손대지 않는다(무회귀). toolChoice 가 없거나 tools 가 없으면 키 자체를 안 싣는다.
@@ -12026,6 +12202,12 @@ const OPENROUTER_ROUTE_FOR_WIP_PROVIDER = {
   glm: 'openrouter/z-ai/glm-5.3',
 } as const;
 
+/** Resolve a review model shortcut before either provider inference or the wire call. */
+export function resolveReviewModelAlias(model: string): string {
+  const resolved = resolveModelAlias(model.trim())!;
+  return OPENROUTER_ROUTE_FOR_WIP_PROVIDER[resolved.toLowerCase() as keyof typeof OPENROUTER_ROUTE_FOR_WIP_PROVIDER] ?? resolved;
+}
+
 /** Top-level resolver. Honors user-config first; falls through to
  *  env-var / auto-detect when provider is 'auto'. */
 export function getProviderForConfig(

package/src/loops/checker.ts

@@ -33,6 +33,9 @@ export interface CheckEntry {
   expectedVersion?: string;
   /** Registry graph path, supplied only by graph inventory. */
   file?: string;
+  /** LOOP-PRUNE-1021-FU 판정 재료 — cron-shell·미등록 행이 실은 crontab 명세(그래프 루프에는 없다). */
+  cron?: string;
+  command?: string;
   enabled: boolean;
   registered: boolean;
 }
@@ -317,3 +320,100 @@ export function observeLoopCheck(results: CheckResult[], scope: LoopScope, deps:
   catch (error) { if (existsSync(tmp)) unlinkSync(tmp); throw error; }
   return counts;
 }
+
+// ── LOOP-PRUNE-1021-FU 정리 판정 (내부 문서 `loop-lineage-1021` · 0.2.36) ─────
+/** 무실행 은퇴 한계 — off 상태가 원장으로 최근 14일 실행이 증명될 때만 은퇴 후보가 된다. */
+export const PRUNE_IDLE_DAYS = 14;
+/** 활성 루프 상한 — alive 가 25 를 넘으면 접기·은퇴 판정을 먼저 치른다. */
+export const PRUNE_ALIVE_LIMIT = 25;
+
+export interface PruneFoldGroup { family: string; ids: string[]; }
+export interface PruneUnregisteredRow { id: string; cron?: string; command?: string; }
+export interface PruneJudgment {
+  /** 14일 무실행이 원장으로 증명된 은퇴 후보(off). */
+  idleRetire: string[];
+  /** 실행 기록이 없어 무실행을 증명할 수 없는 항목 — 은퇴 후보에서 제외한다. */
+  idleUnproven: string[];
+  /** 등록되지 않은 elanous 크론 행 — 등록/제거 판정에 넘긴다. */
+  unregistered: PruneUnregisteredRow[];
+  /** 같은 일을 하는 elanous:* 형제 슬롯 가족 — 그래프 루프·원장 해시는 접지 않는다. */
+  foldGroups: PruneFoldGroup[];
+  /** 활성 루프 수와 25 한도 판정. */
+  alive: { count: number; limit: number; within: boolean };
+  /** 운영 이름이 없는 원장 해시 id — 명명 대상. */
+  unnamed: string[];
+}
+
+/** elanous:* 슬롯의 가족 이름 — namedCronIds 의 -N 접미와 자리 슬롯(:SEAT)을 원래 가족으로 되돌린다. */
+function pruneFoldFamily(id: string): string | undefined {
+  if (!id.startsWith('elanous:')) return undefined;
+  const seat = /^elanous:([^:]+):[^:]+$/.exec(id);
+  if (seat) return `elanous:${seat[1]}`;
+  const sibling = /^elanous:(.+)-\d+$/.exec(id);
+  return `elanous:${sibling ? sibling[1] : id.slice('elanous:'.length)}`;
+}
+
+/** LOOP-PRUNE-1021-FU — CheckResult 원장 위에서 무실행 은퇴·미등록 정리·형제 접기·alive ≤ 25·이름 없는 해시를 판정한다. */
+export function pruneJudgment(results: readonly CheckResult[], opts: { now?: Date } = {}): PruneJudgment {
+  const now = opts.now ?? new Date();
+  const idleMs = PRUNE_IDLE_DAYS * 24 * 60 * 60_000;
+  const idleRetire: string[] = [];
+  const idleUnproven: string[] = [];
+  const unregistered: PruneUnregisteredRow[] = [];
+  const unnamed: string[] = [];
+  const families = new Map<string, string[]>();
+  let aliveCount = 0;
+  for (const result of results) {
+    if (result.state === 'alive') aliveCount++;
+    if (result.state === 'unregistered') {
+      unregistered.push({
+        id: result.id,
+        ...(result.cron ? { cron: result.cron } : {}),
+        ...(result.command ? { command: result.command } : {}),
+      });
+    }
+    if (result.state === 'off') {
+      const ran = result.lastRunAt && Number.isFinite(Date.parse(result.lastRunAt)) ? Date.parse(result.lastRunAt) : undefined;
+      if (ran === undefined) idleUnproven.push(result.id);
+      else if (now.getTime() - ran > idleMs) idleRetire.push(result.id);
+    }
+    if (/^[0-9a-f]{8,}$/.test(result.id)) unnamed.push(result.id);
+    const family = pruneFoldFamily(result.id);
+    if (family) {
+      const group = families.get(family) ?? [];
+      group.push(result.id);
+      families.set(family, group);
+    }
+  }
+  const foldGroups: PruneFoldGroup[] = [];
+  for (const [family, ids] of families) {
+    if (ids.length < 2) continue;
+    foldGroups.push({ family, ids: [...ids].sort() });
+  }
+  const judgment: PruneJudgment = {
+    idleRetire,
+    idleUnproven,
+    unregistered,
+    foldGroups,
+    alive: { count: aliveCount, limit: PRUNE_ALIVE_LIMIT, within: aliveCount <= PRUNE_ALIVE_LIMIT },
+    unnamed,
+  };
+  debug.log('loop.checker', 'prune', {
+    idleRetire: idleRetire.length, idleUnproven: idleUnproven.length, unregistered: unregistered.length,
+    folds: foldGroups.length, alive: aliveCount, unnamed: unnamed.length,
+  });
+  return judgment;
+}
+
+/** LOOP-PRUNE-1021-FU — PruneJudgment 을 사람용 정리 판정 줄로 렌더한다(loop status --all 인간 출력 꼬리). */
+export function pruneText(judgment: PruneJudgment): string {
+  const lines = [
+    `무실행 은퇴 ${judgment.idleRetire.length}: ${judgment.idleRetire.join(', ') || '없음'}`,
+    `무실행 미증명 ${judgment.idleUnproven.length}: ${judgment.idleUnproven.join(', ') || '없음'}`,
+    `미등록 ${judgment.unregistered.length}: ${judgment.unregistered.map(row => row.command ? `${row.id} (${row.command})` : row.id).join(', ') || '없음'}`,
+    `형제 접기 ${judgment.foldGroups.length}: ${judgment.foldGroups.map(group => `${group.family}[${group.ids.join('+')}]`).join(', ') || '없음'}`,
+    `alive ${judgment.alive.count}/${judgment.alive.limit} ${judgment.alive.within ? '한도 이내' : '한도 초과'}`,
+    `이름 없는 해시 ${judgment.unnamed.length}: ${judgment.unnamed.join(', ') || '없음'}`,
+  ];
+  return lines.join('\n');
+}