elanous 0.2.35 → 0.2.37

package/src/input-core/context-key-runtime.ts

@@ -0,0 +1,21 @@
+import { createContextKeyService, type ContextKeyService, type ContextKeys } from './context-keys.js';
+
+// Shared lazy singleton for context-key consumers outside the dashboard.
+let service: ContextKeyService | null = null;
+
+export function getRuntimeContextKeyService(): ContextKeyService {
+  if (!service) service = createContextKeyService();
+  return service;
+}
+
+export function getRuntimeContextKeys(): Readonly<ContextKeys> {
+  return getRuntimeContextKeyService().keys;
+}
+
+export function updateRuntimeContextKeys(patch: Partial<ContextKeys>): void {
+  getRuntimeContextKeyService().update(patch);
+}
+
+export function resetRuntimeContextKeysForTests(): void {
+  service = null;
+}

package/src/instance/test-write-guard-real-transport.fixture.ts

@@ -0,0 +1,52 @@
+// Child fixture for test-write-guard.test.ts (TEST-PROD-LEAK-2 ledger): call-through wrappers installed over
+// the ORIGINAL spill and send functions must not soften the outbound-alert guard. spillLongContent gets a
+// mock.module call-through wrapper (not a fake — it delegates to the original) that counts operational S3
+// upload attempts, and the original curl send primitive gets a bare pass-through spy that counts external
+// sends. The refusal must fire BEFORE spillLongContent runs, so the ledger prints 0 s3Uploads and 0
+// curlCalls alongside the refusal reason. Prints {refused, refusalReason, curlCalls, s3Uploads}.
+import { mock, spyOn } from 'bun:test';
+import * as childProcess from 'node:child_process';
+
+// Pass-through wrapper over the original external-send primitive (curl via execFileSync), installed before
+// outbound-alert is imported so even the module-load capture of the «real» sender sees a wrapper, not a fake.
+const sendWrapper = spyOn(childProcess, 'execFileSync');
+
+const spill = await import('../storage/content-spill.js');
+const originalSpill = spill.spillLongContent;
+let s3Uploads = 0;
+await mock.module('../storage/content-spill.js', () => ({
+  ...spill,
+  spillLongContent: (...args: Parameters<typeof originalSpill>) => {
+    s3Uploads += 1; // every spill that reaches the original is an operational S3 upload attempt
+    return originalSpill(...args);
+  },
+}));
+
+const { sendTelegramDirect } = await import('../domains/outbound-alert.js');
+const { getUserConfig } = await import('../user-config.js');
+const base = getUserConfig();
+const config = { ...base, telegram: { ...base.telegram, channels: undefined, botToken: '2:fake', homeChannel: 2 } } as typeof base;
+type DirectDeps = NonNullable<Parameters<typeof sendTelegramDirect>[2]>;
+const deps = { config } as DirectDeps;
+// LEAK2_INJECT_SENDRAW=1 also injects a real (non-test-double) send transport into the delivery deps — a
+// plain curl-invoking function, no mock scaffolding — so the companion ledger proves the guard refuses an
+// injected external transport, not merely an empty one.
+if (process.env.LEAK2_INJECT_SENDRAW === '1') {
+  (deps as { sendRaw?: (url: string) => string }).sendRaw = (url) =>
+    childProcess.execFileSync('curl', ['-sS', url], { encoding: 'utf8' }) as string;
+  // An injected transport turns the external branch off (:710 — a test double cannot target the ops
+  // universe), so the companion ledger proves the ops-routed branch: the routing roots resolve inside the
+  // ops universe, exactly as production does, and the guard refuses it faked or not.
+  const { EXTRA_OPS_ROOTS_ENV } = await import('../instance/test-write-guard.js');
+  const { getElanousConfigDir } = await import('../elanous-config-dir.js');
+  process.env[EXTRA_OPS_ROOTS_ENV] = getElanousConfigDir();
+}
+let refused = false;
+let refusalReason = '';
+try {
+  sendTelegramDirect('private-alert-body', 'ops-alert', deps);
+} catch (e) {
+  refused = true;
+  refusalReason = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+console.log(JSON.stringify({ refused, refusalReason, curlCalls: sendWrapper.mock.calls.length, s3Uploads }));

package/src/light-cli.ts

@@ -11,7 +11,7 @@ export async function runLightCli(route: LightCliRoute): Promise<void> {
   // warns when the removed ELANOUS_CONFIG_DIR env var disagrees with it.
   // Preserve that observable warning on hot routes without loading the
   // resolver for the common case where the ignored env var is absent.
-  if (['msg', 'pty', 'logs', 'tasks'].includes(route) && process.env.ELANOUS_CONFIG_DIR !== undefined) {
+  if (['msg', 'pty', 'logs', 'tasks', 'tasks-read'].includes(route) && process.env.ELANOUS_CONFIG_DIR !== undefined) {
     const { getElanousConfigDir } = await import('./elanous-config-dir.js');
     getElanousConfigDir();
   }
@@ -45,6 +45,11 @@ export async function runLightCli(route: LightCliRoute): Promise<void> {
       registerTasksCommands(program);
       break;
     }
+    case 'tasks-read': {
+      const { registerTaskReadCommands } = await import('./cli/tasks-read-cli.js');
+      registerTaskReadCommands(program);
+      break;
+    }
     case 'pty': {
       const { registerPtyTakeoverCommands } = await import('./cli/pty-takeover-cli.js');
       registerPtyTakeoverCommands(program);

package/src/llm/route-decision.ts

@@ -8,6 +8,7 @@
 
 import type { LLMProviderName, ReasoningLevel, LlmRoutePolicyConfig } from '../user-config.js';
 import { classifyMissionTier1, type MissionKind } from './mission-router.js';
+import type { SessionSource } from '../session/index.js';
 import { lookupLlmTierSpec } from '../model-tier/llm-tier-map.js';
 
 export type RouteDecisionSource = 'explicit-pin' | 'codex-tier-policy' | 'legacy-default' | 'active-provider-default' | 'execution-backend';
@@ -111,6 +112,8 @@ export interface ResolveRouteDecisionInput {
   provider: LLMProviderName;
   configuredModel?: string;
   text: string;
+  /** Telegram keeps its non-deep coding tier; other surfaces retain the configured quick model. */
+  surface?: SessionSource;
   /** A per-turn/slash/user model choice.  It always wins. */
   explicitModel?: string;
   routePolicy?: LlmRoutePolicyConfig;
@@ -145,6 +148,16 @@ export function resolveRouteDecision(input: ResolveRouteDecisionInput): RouteDec
     };
   }
   const policyMode = input.routePolicy?.mode;
+  // Unspecified callers keep the configured quick model for compatibility; Telegram alone owns the coding-tier exception.
+  if (input.provider === 'openai-codex' && input.surface !== 'telegram' && policyMode === undefined && mission === 'quick' && input.configuredModel) {
+    return {
+      provider: input.provider,
+      model: input.configuredModel,
+      source: 'active-provider-default',
+      rationale: 'configured model preserved for quick mission',
+      mission,
+    };
+  }
   if (input.provider === 'openai-codex' && policyMode !== 'active-provider') {
     const deep = mission === 'plan' || mission === 'review';
     const tier = deep ? 'best' : 'better';

package/src/llm-tool-name.ts

@@ -0,0 +1,37 @@
+/** Provider wire names have a deliberately smaller alphabet than MCP names.
+ * Keep the source name in the TUI/tool catalog and use this reversible map
+ * only for one provider request and its returned tool calls. */
+export interface ProviderToolNameMap {
+  toProviderName(name: string): string;
+  toOriginalName(name: string): string;
+}
+
+export function sanitizeProviderToolName(name: string): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return sanitized.length > 0 ? sanitized : 'tool';
+}
+
+/** Build a deterministic, collision-free mapping for the complete request
+ * namespace. Repeated source names intentionally share one wire name. */
+export function createProviderToolNameMap(names: readonly string[]): ProviderToolNameMap {
+  const originalToProvider = new Map<string, string>();
+  const providerToOriginal = new Map<string, string>();
+
+  for (const original of names) {
+    if (originalToProvider.has(original)) continue;
+
+    const base = sanitizeProviderToolName(original);
+    let candidate = base;
+    let suffix = 2;
+    while (providerToOriginal.has(candidate)) {
+      candidate = `${base}__${suffix++}`;
+    }
+    originalToProvider.set(original, candidate);
+    providerToOriginal.set(candidate, original);
+  }
+
+  return {
+    toProviderName: (name) => originalToProvider.get(name) ?? sanitizeProviderToolName(name),
+    toOriginalName: (name) => providerToOriginal.get(name) ?? name,
+  };
+}

package/src/llm-tool-schema.ts

@@ -0,0 +1,35 @@
+/** 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;
+}
+
+/** 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-wellformed.ts

@@ -0,0 +1,70 @@
+// ── LLM 요청 본문 서로게이트 정리 (TUI-RECOVER-SKIPS-CREDITS · 0.2.36 · 2026-10-22 · OP P0) ──────────
+//
+// 🚨 실물(n8n 세션 · 설치본 99edcfa): 매 턴 즉시 실패 «자동 회복 2회 실패».
+//   grok 원문 `Failed to parse the request body as JSON: messages[19].content: unexpected end of hex escape`
+//   ⊕ 같은 요청에 codex `400 {"detail":"Bad Request"}`. 크레딧·폴백 순서 문제가 아니다 — 이력의 글 하나에
+//   «짝 없는 서로게이트»(이모지를 UTF-16 단위로 자른 반토막)가 섞여 JSON 본문이 깨졌다. 새 세션⊕요약도 그 글을 싣는다.
+// ⭐ 보내기 직전에 모든 문자열의 짝 없는 서로게이트를 U+FFFD 로 바꾼다 — 바뀐 메시지만 새로 만든다.
+//
+// 세 얼굴: 관측 = debug.log('llm.request', 'lone-surrogate-fixed', { messages, strings }) · 인지 = 짝 없는 서로게이트 ·
+//   힐링 = U+FFFD 치환(글 하나가 깨져도 턴은 돈다) · 실패 없음.
+
+/** 짝 없는 서로게이트를 U+FFFD 로 — 바뀌었으면 새 문자열. */
+export function wellFormedString(value: string): string {
+  const fn = (value as { toWellFormed?: () => string }).toWellFormed;
+  if (typeof fn === 'function') return fn.call(value);
+  return value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '�');
+}
+
+function isWellFormed(value: string): boolean {
+  const fn = (value as { isWellFormed?: () => boolean }).isWellFormed;
+  if (typeof fn === 'function') return fn.call(value);
+  return wellFormedString(value) === value;
+}
+
+/** 값 속 문자열(객체 «키» 포함)을 훑어 고친다 — 바뀐 곳이 없으면 같은 참조를 돌려준다.
+ *  깊이 제한은 두지 않는다(깊은 곳에 남으면 본문이 그대로 깨진다 · r1 must-fix) — 순환은 지금 걷는 경로 집합으로 끊는다. */
+function fixValue(value: unknown, count: { strings: number }, path: WeakSet<object>): unknown {
+  if (typeof value === 'string') {
+    if (isWellFormed(value)) return value;
+    count.strings += 1;
+    return wellFormedString(value);
+  }
+  if (value === null || typeof value !== 'object') return value;
+  if (path.has(value)) return value;
+  path.add(value);
+  try {
+    if (Array.isArray(value)) {
+      let out: unknown[] | null = null;
+      value.forEach((item, i) => {
+        const next = fixValue(item, count, path);
+        if (next !== item) { out ??= [...value]; out[i] = next; }
+      });
+      return out ?? value;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return value;
+    let changed = false;
+    const entries = Object.entries(value as Record<string, unknown>).map(([key, item]) => {
+      const nextKey = fixValue(key, count, path) as string;
+      const next = fixValue(item, count, path);
+      if (nextKey !== key || next !== item) changed = true;
+      return [nextKey, next] as const;
+    });
+    return changed ? Object.fromEntries(entries) : value;
+  } finally {
+    path.delete(value);
+  }
+}
+
+/** 메시지 배열 — 고친 메시지 수·문자열 수와 함께. 바뀐 게 없으면 같은 배열. */
+export function wellFormedLLMMessages<T>(messages: readonly T[]): { messages: T[]; fixedMessages: number; fixedStrings: number } {
+  const count = { strings: 0 };
+  let fixedMessages = 0;
+  let out: T[] | null = null;
+  messages.forEach((message, i) => {
+    const next = fixValue(message, count, new WeakSet<object>()) as T;
+    if (next !== message) { fixedMessages += 1; out ??= [...messages]; out[i] = next; }
+  });
+  return { messages: out ?? (messages as T[]), fixedMessages, fixedStrings: count.strings };
+}

package/src/llm.ts

@@ -2,7 +2,8 @@
 // Unified streaming interface for Grok (xAI), OpenAI, Anthropic, Local (OpenAI-compatible).
 // Auto-routes based on model name prefix, or picks the first available provider.
 
-import { createHash } from 'node:crypto';
+import { wellFormedLLMMessages } from './llm-wellformed.js';
+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';
@@ -60,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 { 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.
@@ -275,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
@@ -358,6 +416,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;
   /**
@@ -2555,7 +2615,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 => ({
@@ -2564,7 +2624,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),
     },
   }));
 }
@@ -4460,6 +4522,12 @@ function providerByName(name: string): LLMProvider | undefined {
   return PROVIDERS[name] ?? automaticProviderCandidates().find((candidate) => candidate.name === name);
 }
 
+/** TUI-400-AUTOHEAL-FALLBACK — 같은 턴에서 `failedProviders` 가 실패했을 때 `llm.fallbackChain`(⊕ auto 후보)의
+ *  «다음» 공급자. 턴 안 폴백과 같은 해석(`explainFallbackCandidates`)을 그대로 쓴다 — 체인을 따로 읽지 않는다. */
+export function nextTurnFallbackProvider(failedProviders: readonly string[]): LLMProvider | undefined {
+  return firstAvailableFallbackProvider(new Set(failedProviders), {});
+}
+
 function firstAvailableFallbackProvider(attempted: ReadonlySet<string>, opts: LLMOpts): LLMProvider | undefined {
   // A candidate may lose its credential between chain enumeration and the
   // switch. Keep scanning the ordered chain instead of stopping at that slot.
@@ -4745,6 +4813,11 @@ async function consumeProviderText(
   let full = '';
   let usage: ObservedUsage | undefined;
   try {
+    const wf = wellFormedLLMMessages(messages);
+    if (wf.fixedMessages > 0) {
+      debug.log('llm.request', 'lone-surrogate-fixed', { site: 'streamLLM', provider: provider.name, messages: wf.fixedMessages, strings: wf.fixedStrings }, { level: 'warn' });
+      messages = wf.messages;
+    }
     iterator = (provider.streamChat
       ? provider.streamChat(messages, opts)
       : provider.chat(messages, opts))[Symbol.asyncIterator]();
@@ -4856,7 +4929,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 });
@@ -5863,7 +5936,7 @@ const TOOL_LOOP_PHASE_DIRECTIVES: Record<ToolLoopFollowupPhase, (autoNarrowedRea
     + 'Stop gathering more files and run the code, tests, or repro command first via RunShell/Bash, or answer in plain text if execution is unnecessary.',
   'repair-action': () =>
     'REPAIR ACTION REQUIRED — execution has already failed or a debugging repair step is armed. '
-    + 'Stop gathering more files and move to Edit/Write/RunShell/Bash or a narrow code-intel followup (Read/Lsp/AstGrep/Grep content/count), '
+    + 'Stop gathering more files and move to Edit/Write/RunShell/Bash or a narrow code-intel followup (Read/ListDir/Lsp/AstGrep/Grep content/count), '
     + 'ops ledger/delegate tools (MsgList/MsgPost/MsgAck/Checklist*/AgentOutput) still run, '
     + 'or answer in plain text if no code change is needed (e.g. a read-only investigation whose finding is the deliverable).',
   'verify-action': () =>
@@ -7800,6 +7873,10 @@ const REPAIR_ACTION_TOOLS = new Set([
   'Plan',
   'MarkStepDone',
   'Read',
+  // ListDir is always one directory, never recursive — as narrow as Read. A failed step
+  // is often «is the output there?»; rejecting it pushed the model to `ls` via shell
+  // (n8n session 10-22: ListDir show_hidden=true ×2 rejected after a benign exit 128).
+  'ListDir',
   'Lsp',
   'AstGrep',
   'ast_grep_search',
@@ -8088,17 +8165,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).
@@ -8225,25 +8304,37 @@ function applyCodexBehaviorGuard(
   return enabled;
 }
 
+function orchestrationId(): string {
+  return randomUUID();
+}
+
 export async function streamLLMWithTools(
   messages: LLMMessage[],
   handlers: StreamWithToolsHandlers,
   opts: LLMOpts & { provider?: LLMProvider; missionContext?: { missionId: string; phaseId: string; onOverload?: (info: { turn: number; consecutiveFailures: number; reason: string }) => void; pollSignal?: () => { kind: 'abort' | 'pause'; reason?: string } | undefined }; contextStrategy?: import('./agent-substrate/context-strategy.js').ContextStrategy;
+    /** TUI-400-AUTOHEAL-FALLBACK — 이 턴을 «이 공급자부터» 연다(`provider` 와 달리 폴백은 그대로 허용).
+     *  모델은 그 공급자의 기본 모델(앞 공급자 모델 이름은 안 옮긴다 — 호출부가 `model` 을 비운다). */
+    initialProvider?: LLMProvider;
+    /** 이 턴 폴백 후보에서 뺄 공급자(이미 같은 턴에서 실패한 쪽 — 되돌아가지 않게). */
+    skipProviders?: readonly string[];
   } = {},
 ): Promise<string> {
-  const provider = opts.provider ?? resolveDefaultProvider(opts.model);
+  const provider = opts.provider ?? opts.initialProvider ?? resolveDefaultProvider(opts.model);
   const initial = finalizeStreamingProviderModel(provider, opts.model ?? provider.defaultModel);
   let activeProvider = initial.provider;
   let activeModel = initial.model;
   opts.onResolvedProvider?.(activeProvider.name, activeModel);
-  const attemptedProviders = new Set<string>([activeProvider.name]);
+  const attemptedProviders = new Set<string>([activeProvider.name, ...(opts.skipProviders ?? [])]);
   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,
@@ -8794,7 +8885,34 @@ export async function streamLLMWithTools(
           activeModel = finalized.model;
           opts.onResolvedProvider?.(activeProvider.name, activeModel);
           turnOpts = { ...turnOpts, model: activeModel };
-          streamIter = activeProvider.streamChat!(history, turnOpts)[Symbol.asyncIterator]();
+          // 짝 없는 서로게이트(잘린 이모지)가 섞이면 공급자가 본문 JSON 을 못 읽는다(10-22 n8n 매 턴 400) — 이력 자체를 고친다(다음 요청에 다시 안 실리게).
+          const wf = wellFormedLLMMessages(history);
+          if (wf.fixedMessages > 0) {
+            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);
+          }
+          // 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 })),
@@ -8971,7 +9089,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
@@ -9361,13 +9479,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,
@@ -11372,7 +11500,12 @@ 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)));
+      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 가 없으면 키 자체를 안 싣는다.
@@ -11985,7 +12118,11 @@ export function anyProviderAvailable(userConfig?: UserConfig): boolean {
       } catch { return false; }
     }
   } catch { /* fall through to env check */ }
-  return Object.values(PROVIDERS).some(p => p.name !== 'bedrock' && p.name !== 'opengateway' && p.available()); // 명시 전용 공급자는 auto 가용성 아님
+  if (Object.values(PROVIDERS).some(p => p.name !== 'bedrock' && p.name !== 'opengateway' && p.available())) return true; // 명시 전용 공급자는 auto 가용성 아님
+  // 시험 fake 를 «공급자 있음» 으로 치는 것은 격리 라이브 TUI 무대가 명시로 켤 때만(ELANOUS_TEST_FAKE_LLM_AS_PROVIDER=1).
+  //   ⛔ gate 시험 env 는 ELANOUS_TEST_FAKE_LLM=1 을 «전역» 으로 켠다(scripts/lib/gate-test-env.ts) — 그 스위치만으로 가용성이
+  //   참이 되면 «아무것도 없으면 false» 계약과 가용성으로 갈리는 기능(dart·dig-engine 등)이 gate 에서 모두 바뀐다(열차 #30208 introduced 2).
+  return process.env.ELANOUS_TEST_FAKE_LLM_AS_PROVIDER === '1' && testFakeLlmEnabled();
 }
 
 /** 직결 배선이 없는 계열 → OpenRouter 에서 그 벤더의 대표 모델(사다리 `openrouter` 에 선 것). */
@@ -11995,6 +12132,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(