elanous 0.2.42 → 0.2.44

package/src/llm/provider-credentials.ts

@@ -29,6 +29,7 @@
 
 import { BUILTIN_CATALOG } from '../intelligence-map/model-catalog.js';
 import { debug } from '../debug/log.js';
+import { PROVIDER_ENV_SPEC } from '../setup/llm-env-detect.js';
 
 /** provider → API-key env var. catalog 이 envKey 를 안 다는 provider 의 명시 보정.
  *  ⚠️ catalog 파생이 이미 값을 주는 provider 는 **여기 적지 않는다** — 이중 진실을 만들지 않기 위해. */
@@ -145,7 +146,7 @@ export function isKeylessProvider(provider: string | undefined): boolean {
 }
 
 /** 키가 어디서 왔나 — 관측·진단용(제1원칙: "왜 이 키인가"가 로그로 답해져야 한다). */
-type CredentialSource = 'rotation' | 'env' | 'inherited' | 'none';
+type CredentialSource = 'rotation' | 'env' | 'secret-store' | 'inherited' | 'none';
 
 interface ResolvedCredential {
   /** 해석된 키. 없으면 undefined(호출자가 provider 기본 인증으로 폴백하거나 명시 실패). */
@@ -175,6 +176,8 @@ interface ResolveCredentialInput {
   /** base config 의 `llm.provider` — 전환 여부 판정용. */
   baseProvider?: string | undefined;
   env?: NodeJS.ProcessEnv;
+  /** 이미 조회한 SecretStore 값. 값은 런타임 메모리에서만 전달한다. */
+  secretStoreApiKey?: string | undefined;
 }
 
 /**
@@ -183,8 +186,9 @@ interface ResolveCredentialInput {
  * 우선순위(대표 결정 (a)):
  *   ① `llm.rotation` 에서 같은 provider 엔트리의 apiKey (config·감사 가능)
  *   ② `providerEnvKey(provider)` 로 읽은 env
- *   ③ provider 가 **안 바뀐** 경우에 한해 base `llm.apiKey` 상속
- *   ④ 없음 — 호출자가 판단(구독/OAuth provider 는 이게 정상일 수 있다)
+ *   ③ 기존 SecretStore (`providerEnvKey` 와 같은 ID)
+ *   ④ provider 가 **안 바뀐** 경우에 한해 base `llm.apiKey` 상속
+ *   ⑤ 없음 — 호출자가 판단(구독/OAuth provider 는 이게 정상일 수 있다)
  *
  * ⚠️ ③ 이 마지막인 것이 이 수리의 핵심이다. 종전엔 ③ 이 **무조건 첫 번째**였고, 그래서 provider 가
  * 바뀌어도 옛 provider 의 키가 따라갔다(= 401 의 근본). provider 가 바뀌었으면 base 키는 **틀린 키**다.
@@ -221,10 +225,20 @@ export function resolveProviderCredential(input: ResolveCredentialInput): Resolv
 
   // ② env — provider 별 표준 env var.
   const envKey = providerEnvKey(provider);
-  const fromEnv = envKey ? env[envKey]?.trim() : undefined;
-  if (fromEnv) return { apiKey: fromEnv, source: 'env', ...(envKey ? { envKey } : {}), ...withUrl };
+  const envSpec = PROVIDER_ENV_SPEC.find((spec) => spec.provider === provider);
+  const envCandidates = [...new Set([envKey, envSpec?.primaryKeyEnv, ...(envSpec?.aliasKeyEnvs ?? [])]
+    .filter((name): name is string => Boolean(name)))];
+  for (const candidate of envCandidates) {
+    const fromEnv = env[candidate]?.trim();
+    if (fromEnv) return { apiKey: fromEnv, source: 'env', envKey: candidate, ...withUrl };
+  }
+
+  // ③ SecretStore — setup service-keys uses providerEnvKey(provider) as its secret ID.
+  // The value is never copied to config or observability fields.
+  const stored = input.secretStoreApiKey?.trim();
+  if (stored) return { apiKey: stored, source: 'secret-store', ...(envKey ? { envKey } : {}), ...withUrl };
 
-  // ③ 상속 — **provider 가 확실히 그대로일 때만.** 바뀌었으면 base 키는 다른 provider 것이라 틀렸다.
+  // ④ 상속 — **provider 가 확실히 그대로일 때만.** 바뀌었으면 base 키는 다른 provider 것이라 틀렸다.
   //   ⚠️ 리뷰 must-fix(#5488 2R): 종전 판정은 `!switched` 였는데 `baseProvider` 가 없으면 switched=false
   //      가 되어 **전환 여부를 모르는데 상속**했다 = 401 재현. 상속은 `provider === baseProvider` 가
   //      **명시적으로 참**일 때만 허용한다(모르면 상속 안 함 = fail-closed).
@@ -240,6 +254,54 @@ export function resolveProviderCredential(input: ResolveCredentialInput): Resolv
   return { source: 'none', ...(envKey ? { envKey } : {}), ...withUrl };
 }
 
+function canReadHostSecretStore(env: NodeJS.ProcessEnv): boolean {
+  if (env.NODE_ENV === 'test' || env.ELANOUS_TEST_HOME?.trim()) return false;
+  const bunMain = (globalThis as { Bun?: { main?: string } }).Bun?.main;
+  if (bunMain && /\.(test|spec)\.[cm]?[jt]sx?$/.test(bunMain)) return false;
+  try {
+    const { resolveCurrentInstance } = require('../instance/current.js') as typeof import('../instance/current.js');
+    if (resolveCurrentInstance().kind !== 'prod') return false;
+    // `input.env` is injectable for deterministic callers. Preserve the same
+    // test-universe rule when it supplies a non-production parent stamp.
+    if (env.ELANOUS_STATE_DIR?.trim()) {
+      const { resolveInstance } = require('../instance/resolve.js') as typeof import('../instance/resolve.js');
+      if (resolveInstance({ stampedStateDir: env.ELANOUS_STATE_DIR }).kind !== 'prod') return false;
+    }
+    return true;
+  } catch {
+    // If the operational universe cannot be established, fail closed on host secrets.
+    return false;
+  }
+}
+
+/** Async runtime lookup for keys written by `setup service-keys`. Existing
+ * rotation and environment precedence is resolved before the SecretStore is
+ * queried; a legacy same-provider config key remains the final compatibility
+ * source. The secret value is returned only to the caller for the live request. */
+export async function resolveProviderCredentialAsync(
+  input: ResolveCredentialInput,
+  getSecret?: (id: string) => Promise<string | undefined>,
+): Promise<ResolvedCredential> {
+  const withoutStore = resolveProviderCredential(input);
+  if (withoutStore.source === 'rotation' || withoutStore.source === 'env') return withoutStore;
+  const secretId = providerEnvKey(input.provider);
+  if (!secretId) return withoutStore;
+  const env = input.env ?? process.env;
+  // Bun's test runner changes HOME, but the OS SecretStore (for example the
+  // macOS Keychain) is host-global. Never let those credentials alter a test's
+  // provider selection; callers can still inject a deterministic reader.
+  if (!getSecret && !canReadHostSecretStore(env)) return withoutStore;
+  let stored: string | undefined;
+  try {
+    if (getSecret) stored = await getSecret(secretId);
+    else {
+      const { getSecretAsync } = await import('../nexus/config/secrets/index.js');
+      stored = await getSecretAsync(secretId);
+    }
+  } catch { /* keep the legacy source fallback; never expose backend errors */ }
+  return resolveProviderCredential({ ...input, secretStoreApiKey: stored });
+}
+
 /**
  * 해석 결과를 관측에 남긴다 — 제1원칙(관측 없으면 자기인지·힐링 불가). **키 값은 절대 싣지 않는다**(이름·출처만).
  * 키가 필요한 provider 인데 못 찾은 경우는 warn 으로 올려 401 이 나기 **전에** 보이게 한다.

package/src/llm/provider-failure-evidence.ts

@@ -0,0 +1,44 @@
+export type ProviderFailureEvidence = {
+  httpStatus?: number;
+  providerErrorCode?: string;
+  providerErrorType?: string;
+};
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function safeCode(value: unknown): string | undefined {
+  return typeof value === 'string' && /^[A-Za-z0-9_.-]{1,100}$/.test(value) ? value : undefined;
+}
+
+/** Retain only non-secret structured fields from provider failures. */
+export function providerFailureEvidence(error: unknown): ProviderFailureEvidence {
+  const source = record(error);
+  if (!source) return {};
+
+  let body: Record<string, unknown> | undefined;
+  if (typeof source.bodyText === 'string') {
+    try { body = record(JSON.parse(source.bodyText)); } catch { /* body is not structured JSON */ }
+  }
+  if (!body && typeof source.message === 'string') {
+    const jsonStart = source.message.indexOf('{');
+    if (jsonStart >= 0) {
+      try { body = record(JSON.parse(source.message.slice(jsonStart))); } catch { /* message may be clipped */ }
+    }
+  }
+
+  const nestedError = record(body?.error);
+  const status = source.status;
+  const httpStatus = typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599
+    ? status
+    : undefined;
+  const providerErrorCode = safeCode(nestedError?.code) ?? safeCode(body?.code);
+  const providerErrorType = safeCode(nestedError?.type) ?? safeCode(body?.type);
+
+  return {
+    ...(httpStatus !== undefined ? { httpStatus } : {}),
+    ...(providerErrorCode ? { providerErrorCode } : {}),
+    ...(providerErrorType ? { providerErrorType } : {}),
+  };
+}

package/src/llm.ts

@@ -29,10 +29,13 @@ import {
 import { debug, redactSecrets, redactSecretText } from './debug/log.js';
 import { estimateMessagesTokens } from './tokens.js';
 import { isVerifiedOpenGatewayModel } from './llm/opengateway-models.js';
+import { resolveCodexAccountForRun } from './oauth/codex-account-store.js';
+import { codexOwnerMirrorAuthPath, readCodexOwnerAccessMirror } from './oauth/codex-owner-mirror.js';
 import { llmUsageCostFields } from './budget/llm-cost.js';
 import { accumulateByokUsage } from './llm/openrouter-byok-cost.js';
 import { ACTION_PHASE_OPS_TOOLS, isSteeredShellRejection, REPAIR_PHASE_READ_ONLY_OPS_TOOLS } from './llm/tool-loop-steered-rejection.js';
 import { ToolCallTiming } from './chat/tool-call-timing.js';
+import { recordChildFirstLlmResponse, recordChildFirstLlmStart, recordChildFirstToolCall } from './llm/child-first-llm-observation.js';
 import {
   dispatchWithParallelSafety,
   isSafeForParallel,
@@ -54,6 +57,7 @@ import {
   type ProviderFallbackTerminalVerdict,
 } from './session-runtime/retry-policy.js';
 import { ApiHttpError, fetchApiWithRetry, OverloadFailoverError, type FetchApiWithRetryOpts } from './session-runtime/retry-api.js';
+import { providerFailureEvidence } from './llm/provider-failure-evidence.js';
 import { isShapeRelevantRejection, summarizeCodexRequestShape } from './llm-request-shape.js';
 import { BedrockProvider, isBedrockCompatibleModel, makeBedrockProvider } from './llm/bedrock-provider.js';
 import { OPEN_WEIGHT_TOOL_DISCIPLINE } from './llm/open-weight-discipline.js';
@@ -497,6 +501,9 @@ export interface LLMOpts {
   reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
   /** Tool definitions made available to the model for this turn. */
   tools?: LLMToolSpec[];
+  /** Optional tool pool exposed only to the first tool-loop request. The
+   *  normal `tools` pool remains active for later requests and hydration. */
+  firstTurnTools?: LLMToolSpec[];
   /** Tool-calling forcing for THIS turn. In streamLLMWithTools it forces on
    *  turn 0 only, then reverts to auto so the model can finalize. See ToolChoice. */
   toolChoice?: ToolChoice;
@@ -4395,6 +4402,16 @@ function providerDecisionCandidates(): Array<LLMProvider & { name: ProviderDecis
 
 /** Exported (OB1) so onboarding and `setup` judge «is there a usable ChatGPT/Codex login» exactly as the runtime does. */
 export function codexOAuthAvailable(): boolean {
+  if (process.env.ELANOUS_REMOTE_CODEX_ACCESS_ONLY === '1') {
+    try {
+      const mirrorPath = codexOwnerMirrorAuthPath();
+      const account = resolveCodexAccountForRun(process.env, { storePath: mirrorPath });
+      readCodexOwnerAccessMirror(account.storeKey, { path: mirrorPath });
+      return true;
+    } catch {
+      return false;
+    }
+  }
   try {
     const account = resolveCodexAccount(process.env, { storedHome: (key) => loadTokens(key)?.codexHome });
     if (loadTokens(account.storeKey)) return true;
@@ -4577,7 +4594,8 @@ function configuredFallbackChainSteps(): readonly string[] {
   try {
     const { getUserConfig } = require('./user-config.js') as typeof import('./user-config.js');
     const { normalizeFallbackChain } = require('./oauth/fallback-chain.js') as typeof import('./oauth/fallback-chain.js');
-    return normalizeFallbackChain(getUserConfig().llm.fallbackChain).chain;
+    const llm = getUserConfig().llm;
+    return normalizeFallbackChain(llm.fallbackChain, llm.provider).chain;
   } catch (err) {
     // ⛔ 조용히 삼키면 「설정을 못 읽었다」가 「폴백 후보가 없다」로 «둔갑»한다 —
     //   호출자는 그것을 `fallback candidates exhausted` 로 보고 사람에게 그렇게 말한다.
@@ -5113,11 +5131,16 @@ async function consumeProviderText(
 export async function streamLLM(
   messages: LLMMessage[],
   onChunk: (delta: string, full: string) => void,
-  opts: LLMOpts & { provider?: LLMProvider; initialProvider?: LLMProvider; onResolvedProvider?: (provider: string, model: string) => void } = {},
+  opts: LLMOpts & {
+    provider?: LLMProvider;
+    initialProvider?: LLMProvider;
+    onResolvedProvider?: (provider: string, model: string) => void;
+    skipProviders?: readonly string[];
+  } = {},
 ): Promise<string> {
   const started = Date.now();
-  let activeProvider = opts.provider ?? opts.initialProvider ?? resolveDefaultProvider(opts.model);
-  const attemptedProviders = new Set<string>([activeProvider.name]);
+  let activeProvider = opts.provider ?? opts.initialProvider ?? await resolveDefaultProviderAsync(opts.model);
+  const attemptedProviders = new Set<string>([activeProvider.name, ...(opts.skipProviders ?? [])]);
   let blockedProviders: ProviderFallbackAttempt[] = [];
   let modelOverride = opts.model;
 
@@ -5130,6 +5153,11 @@ export async function streamLLM(
     const activeModel = finalized.model;
     if (getModelFamily(activeModel) === 'claude') assertNoTopLevelToolSchemaCombinators(opts.tools);
     opts.onResolvedProvider?.(activeProvider.name, activeModel);
+    await recordChildFirstLlmStart({
+      provider: activeProvider.name, model: activeModel,
+      ...(activeProvider.name === 'openai-codex' && process.env.ELANOUS_CODEX_ACCOUNT?.trim()
+        ? { accountName: process.env.ELANOUS_CODEX_ACCOUNT.trim() } : {}),
+    });
     debug.log('llm.router', 'streamLLM', {
       provider: activeProvider.name,
       model: activeModel,
@@ -5152,6 +5180,7 @@ export async function streamLLM(
     );
     const full = consumed.full;
     if (consumed.ok) {
+      await recordChildFirstLlmResponse({ status: 'ok' });
       if (consumed.usage !== 'unmeasured') {
         try {
           logAgentTurnUsage(activeModel, consumed.usage, { providerName: activeProvider.name, site: opts.usageSite ?? 'stream-llm', role: opts.usageRole, phase: opts.usagePhase, jobKind: opts.usageJobKind });
@@ -5170,6 +5199,11 @@ export async function streamLLM(
     }
 
     const err: any = consumed.error;
+    await recordChildFirstLlmResponse({
+      status: 'error',
+      ...(Number.isSafeInteger(err?.status) ? { httpStatus: err.status as number } : Number.isSafeInteger(err?.statusCode) ? { httpStatus: err.statusCode as number } : {}),
+      error: err,
+    });
     if (err instanceof OverloadFailoverError && !opts.provider) {
       const switched = activeProvider.name === 'openai-codex'
         ? firstAvailableFallbackProvider(attemptedProviders, opts)
@@ -5196,6 +5230,7 @@ export async function streamLLM(
       model: activeModel,
       durationMs: Date.now() - started,
       message: reason,
+      ...providerFailureEvidence(err),
       ...(isAuthRejectionError(err) ? { authRejected: true } : {}),
     }, { level: 'error' });
     if (opts.provider) {
@@ -5342,6 +5377,44 @@ export function resolveDefaultProvider(model?: string): LLMProvider {
   }
 }
 
+/** Async default resolver for requests that can use keys saved by setup service-keys. */
+export async function resolveDefaultProviderAsync(model?: string): Promise<LLMProvider> {
+  try {
+    // Preserve the established resolver as the default for every credential
+    // source it already handles. Besides avoiding provider-factory churn, this
+    // keeps registered providers and injected resolver implementations intact.
+    const existingProvider = resolveDefaultProvider(model);
+    const { getUserConfig } = require('./user-config.js') as typeof import('./user-config.js');
+    const cfg = getUserConfig();
+    const modelHint = cfg.llm.provider !== 'auto' && !isModelCompatible(cfg.llm.provider, model)
+      ? undefined
+      : model;
+    const decision = decideProviderForConfig(cfg, modelHint);
+    let usedSecretStore = false;
+    const asyncProvider = await getProviderForConfigAsync(cfg, modelHint, undefined, process.env, () => {
+      usedSecretStore = true;
+    });
+    const p = usedSecretStore ? asyncProvider : existingProvider;
+    debug.log('llm.router', 'resolveDefaultProvider', {
+      source: cfg.llm.provider === 'auto' ? 'user-config-auto-decision' : 'user-config',
+      configProvider: cfg.llm.provider,
+      configModel: cfg.llm.model,
+      requestedModel: model,
+      decisionProvider: decision.provider,
+      decisionAuth: decision.auth,
+      resolvedTo: p.name,
+      resolvedModel: p.defaultModel,
+      available: p.available(),
+    }, { level: 'info' });
+    return p;
+  } catch {
+    debug.log('llm.router', 'resolveDefaultProvider-secretstore-fallback', {
+      reason: 'async-provider-resolution-failed',
+    }, { level: 'warn' });
+    return resolveDefaultProvider(model);
+  }
+}
+
 /** Handlers + result for `streamLLMWithTools`. */
 export interface StreamWithToolsHandlers {
   /** Streaming text delta — invoked for every text chunk across all turns. */
@@ -8595,7 +8668,7 @@ export async function streamLLMWithTools(
   const circuit = !opts.provider && !opts.initialProvider
     ? await import('./session-runtime/provider-circuit.js')
     : undefined;
-  const provider = opts.provider ?? opts.initialProvider ?? resolveDefaultProvider(opts.model);
+  const provider = opts.provider ?? opts.initialProvider ?? await resolveDefaultProviderAsync(opts.model);
   const initial = finalizeStreamingProviderModel(provider, opts.model ?? provider.defaultModel);
   let activeProvider = initial.provider;
   let activeModel = initial.model;
@@ -8621,6 +8694,19 @@ export async function streamLLMWithTools(
     }
   }
   opts.onResolvedProvider?.(activeProvider.name, activeModel);
+  await recordChildFirstLlmStart({
+    provider: activeProvider.name, model: activeModel,
+    ...(activeProvider.name === 'openai-codex' && process.env.ELANOUS_CODEX_ACCOUNT?.trim()
+      ? { accountName: process.env.ELANOUS_CODEX_ACCOUNT.trim() } : {}),
+  });
+  const initialToolHandler = handlers.onToolCall;
+  handlers = {
+    ...handlers,
+    onToolCall: (call) => {
+      void recordChildFirstToolCall();
+      initialToolHandler?.(call);
+    },
+  };
   const attemptedProviders = new Set<string>([
     activeProvider.name,
     ...(circuitBlockedInitialProvider ? [circuitBlockedInitialProvider] : []),
@@ -9170,7 +9256,9 @@ export async function streamLLMWithTools(
       const base = {
         ...opts,
         model: activeModel,
-        tools: completionNeedsFinalTurn && !keepToolsNoCall ? [] : activeTools,
+        tools: completionNeedsFinalTurn && !keepToolsNoCall
+          ? []
+          : turn === 0 && opts.firstTurnTools ? opts.firstTurnTools : activeTools,
         remainingFallbacks,
       };
       if (keepToolsNoCall) return { ...base, toolChoice: 'none' as const };
@@ -9303,7 +9391,11 @@ export async function streamLLMWithTools(
           new Promise<{ idle: true }>((res) => { idleTimer = setTimeout(() => res({ idle: true }), streamIdleTimeoutMs); }),
         ]);
         if (step.idle) throw new StreamIdleTimeoutError(streamIdleTimeoutMs);
+        await recordChildFirstLlmResponse({ status: 'ok' });
       } catch (err) {
+        const status = Number.isSafeInteger((err as { status?: unknown })?.status) ? (err as { status: number }).status
+          : Number.isSafeInteger((err as { statusCode?: unknown })?.statusCode) ? (err as { statusCode: number }).statusCode : undefined;
+        await recordChildFirstLlmResponse({ status: 'error', ...(status === undefined ? {} : { httpStatus: status }), error: err });
         if (idleTimer) clearTimeout(idleTimer);
         releaseStreamAttempt(true, err);
         if (err instanceof ApiHttpError && err.status === 400 && providerToolSchemaDiagnostics) {
@@ -12809,14 +12901,14 @@ export function getProviderForConfig(
   }
   const crossFamilyModel = (model || userConfig.llm.model) && resolvedProviderName !== provider;
   if (crossFamilyModel) {
-    const keyPrefix = (userConfig.llm.apiKey || '').slice(0, 7);
-    const keyImplies = keyPrefix.startsWith('sk-ant')
+    const key = userConfig.llm.apiKey || '';
+    const keyImplies = key.startsWith('sk-ant')
       ? 'anthropic'
-      : keyPrefix.startsWith('xai-')
+      : key.startsWith('xai-')
         ? 'grok'
-        : keyPrefix.startsWith('sk-')
+        : key.startsWith('sk-')
           ? 'openai'
-          : keyPrefix
+          : key
             ? 'unknown'
             : 'none';
     const keyMismatch =
@@ -12827,7 +12919,6 @@ export function getProviderForConfig(
       configProvider: provider,
       model: decision.model,
       implied: resolvedProviderName,
-      keyPrefix: keyPrefix || null,
       keyImplies,
       keyMismatch,
     }, { level: 'info' });
@@ -12872,6 +12963,75 @@ export function getProviderForConfig(
   // union without a case here fails loud at first call.
   throw new Error(`unknown provider: ${provider as string}`);
 }
+
+/** Async counterpart used by production request paths. It overlays a SecretStore
+ * credential only on the ephemeral config passed to the provider factory; the
+ * persisted UserConfig is never mutated or saved. */
+export async function getProviderForConfigAsync(
+  userConfig: UserConfig,
+  model?: string,
+  getSecret?: (id: string) => Promise<string | undefined>,
+  env: NodeJS.ProcessEnv = process.env,
+  onSecretStoreCredential?: () => void,
+): Promise<LLMProvider> {
+  const { resolveProviderCredentialAsync } = await import('./llm/provider-credentials.js');
+  const decision = finalizeProviderModelCompatibility(decideProviderForConfig(userConfig, model));
+  let target = decision.provider.startsWith('auto:')
+    ? decision.provider.slice('auto:'.length)
+    : decision.provider;
+
+  // decideProviderForConfig preserves the established env/subscription and
+  // keyless-provider selection. This loop only runs when that resolver found
+  // no synchronous candidate; it then checks persisted setup keys in the same
+  // provider order.
+  if (target === 'auto') {
+    for (const candidate of PROVIDER_DECISION_ORDER) {
+      const credential = await resolveProviderCredentialAsync({
+        provider: candidate,
+        rotation: userConfig.llm.rotation,
+        baseProvider: userConfig.llm.provider,
+        baseApiKey: userConfig.llm.apiKey,
+        env,
+      }, getSecret);
+      if (credential.source !== 'none') {
+        target = candidate;
+        break;
+      }
+    }
+  }
+  if (target === 'auto') return getProviderForConfig(userConfig, model);
+
+  const resolvedModel = decision.provider === 'auto' || decision.model === '(none)'
+    ? defaultModelForProvider(target as ConcreteProviderName)
+    : decision.model;
+
+  const credential = await resolveProviderCredentialAsync({
+    provider: target,
+    rotation: userConfig.llm.rotation,
+    baseProvider: userConfig.llm.provider,
+    baseApiKey: userConfig.llm.apiKey,
+    env,
+  }, getSecret);
+  // Keep the established provider registry/factory path unless this request
+  // actually depends on a setup key. In particular, auto mode may have a
+  // registered provider implementation (test doubles included) that must not
+  // be replaced by a newly constructed provider with an empty ephemeral key.
+  if (credential.source !== 'secret-store') return getProviderForConfig(userConfig, model);
+  onSecretStoreCredential?.();
+  const ephemeralConfig = {
+    ...userConfig,
+    llm: {
+      ...userConfig.llm,
+      provider: target as UserConfig['llm']['provider'],
+      model: resolvedModel,
+      apiKey: credential.apiKey,
+      baseUrl: target === userConfig.llm.provider
+        ? credential.baseUrl ?? userConfig.llm.baseUrl
+        : credential.baseUrl,
+    },
+  };
+  return getProviderForConfig(ephemeralConfig, resolvedModel);
+}
 import { getModelFamily, isGpt6GenerationModel, usesCodexBehaviorGuards } from './models/prompts.js';
 import type { ModelFamily } from './models/prompts.js';
 

package/src/maturity/feature-maturity.ts

@@ -59,10 +59,10 @@ export const FEATURE_MATURITY = {
   },
   // Canonical CLI command names only; aliases inherit their command's grade.
   cliRoot: {
-    preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta',
+    preview: 'beta', pty: 'beta', pr: 'beta', repo: 'beta', role: 'beta', machine: 'beta', image: 'beta', 'agent-env': 'beta', catalog: 'beta',
     where: 'stable', bench: 'beta', shadow: 'beta', llm: 'beta', storage: 'beta', leader: 'beta',
     pod: 'beta', browser: 'beta', questions: 'beta', usage: 'stable', live: 'beta',
-    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', freeze: 'beta', herdr: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
+    research: 'beta', release: 'beta', rfc: 'beta', know: 'beta', life: 'beta', freeze: 'beta', herdr: 'beta', flow: 'beta', seat: 'beta', hq: 'beta', steward: 'beta', coord: 'beta', context: 'beta', 'model-watch': 'beta', doctor: 'stable',
     control: 'beta', resources: 'beta', hooks: 'beta', setup: 'stable', start: 'stable',
     grounding: 'beta', graph: 'beta', loop: 'stable', resource: 'beta', card: 'stable', 'launch-head': 'beta',
     a2a: 'beta', plugin: 'stable', make: 'beta', skills: 'beta', connect: 'beta', import: 'beta',
@@ -82,7 +82,7 @@ export const FEATURE_MATURITY = {
     onboarding: 'beta', login: 'stable', session: 'beta', chat: 'stable', repl: 'stable',
     agent: 'stable', registry: 'beta', tier: 'stable', local: 'beta', scheduler: 'beta',
     attach: 'beta', wf: 'beta', nexus: 'stable', phone: 'beta', token: 'beta',
-    acp: 'beta', voice: 'beta', sim: 'beta',
+    acp: 'beta', voice: 'beta', sim: 'beta', tui: 'system',
     'run-detached': 'system', dogfood: 'system', run: 'system',
   },
   // Canonical names only; aliases inherit their command's grade at lookup.

package/src/mcp/client.ts

@@ -91,6 +91,11 @@ export interface McpToolCallContent {
   [k: string]: unknown;
 }
 
+/** Per-call MCP metadata. `elanousRunId` is only a correlation key. */
+export interface McpCallMeta extends Record<string, unknown> {
+  elanousRunId?: string;
+}
+
 /** The remote server answered with a JSON-RPC `error` envelope.
  *
  *  ⛔⭐ **「서버가 안 된다고 했다」와 「서버에 못 닿았다」는 다른 값이다.**
@@ -749,11 +754,13 @@ export class McpClient {
   async callTool(
     name: string,
     args: Record<string, unknown>,
+    meta?: McpCallMeta,
   ): Promise<McpToolCallResult> {
     this.requireReady('callTool');
     const result = (await this.send('tools/call', {
       name,
       arguments: args,
+      ...(meta && Object.keys(meta).length > 0 ? { _meta: meta } : {}),
     })) as McpToolCallResult;
     return result;
   }

package/src/mcp/proxy-runtime.ts

@@ -44,6 +44,7 @@ import {
   type FeedbackEnvelope,
 } from '../feedback/envelope.js';
 import { mcpMediaJobs, mcpResultImages } from '../feedback/media.js';
+import { getHarnessRunId } from '../harness/harness-space.js';
 import { McpServerError } from './client.js';
 import type { McpClient, McpTool, McpToolCallResult } from './client.js';
 
@@ -278,7 +279,11 @@ export function createMcpProxyRuntime(
         };
       }
       try {
-        const result = await opts.client.callTool(opts.mcpTool.name, req);
+        const runId = (ctx.runId || getHarnessRunId()).trim();
+        // The correlation id is needed only for Aside's delegated return path.
+        // Do not disclose the local run identity to other MCP servers.
+        const meta = opts.serverId === 'aside' && runId ? { elanousRunId: runId } : undefined;
+        const result = await opts.client.callTool(opts.mcpTool.name, req, meta);
         const converted = mcpResultToRunResult(result);
         emitMcpMediaFeedback(converted, ctx);
         const capped = capMcpOutput(converted, {

package/src/mcp/server.ts

@@ -29,6 +29,7 @@ import { buildCliAgentTools } from '../cli/agent-cli.js';
 import { getUserConfig } from '../user-config.js';
 import type { TokenScope } from '../auth/scope.js';
 import { filterToolsForScope, isToolAllowedForScope } from '../nexus/api/mcp-public-allowlist.js';
+import { normalizeRunId } from '../harness/harness-space.js';
 
 // ─── JSON-RPC shapes ─────────────────────────────────────────────
 
@@ -102,6 +103,30 @@ export interface McpServerContext {
   tokenScope?: TokenScope;
 }
 
+/** Accept only an already-safe run identifier from standard MCP params._meta. */
+function mcpRunId(params: Record<string, unknown> | undefined): string | undefined {
+  const meta = params?._meta;
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return undefined;
+  const value = (meta as Record<string, unknown>).elanousRunId;
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) return undefined;
+  const normalized = normalizeRunId(value);
+  return normalized === value ? value : undefined;
+}
+
+function logAsideRunIdDrop(toolName: string, params: Record<string, unknown> | undefined): void {
+  const meta = params?._meta;
+  const raw = meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? (meta as Record<string, unknown>).elanousRunId
+    : undefined;
+  const reason = typeof raw !== 'string'
+    ? 'missing-or-non-string'
+    : !/^[A-Za-z0-9_-]{1,64}$/.test(raw)
+      ? 'invalid-format'
+      : normalizeRunId(raw) !== raw ? 'not-normalized' : 'validation-rejected';
+  try { debug.log('mcp-server.aside', 'elanous-tool-call-run-id-dropped', { toolName, reason }); }
+  catch { /* observation must not block the caller */ }
+}
+
 /** Emit a `system.mcp.proxy_call` user-intent event for a single
  *  tool dispatch. Best-effort — sink failures swallowed upstream by
  *  `userIntentLogger.emit`, and the outer try/catch keeps the
@@ -177,8 +202,20 @@ export async function handleMcpRequest(
         const args = (req.params?.arguments as Record<string, unknown>) ?? {};
         const surface = ctx.surface ?? 'mcp';
         const rt = getToolRuntime(name);
+        const runId = ctx.clientName === 'aside' ? mcpRunId(req.params) : undefined;
+        if (ctx.clientName === 'aside' && !runId) logAsideRunIdDrop(name, req.params);
+        const asideReturn = runId !== undefined;
         const isExposedOnSurface = listToolRuntimes(surface).some(runtime => runtime.id === rt?.id);
         if (!rt || !isExposedOnSurface) {
+          if (asideReturn) {
+            try {
+              debug.log('mcp-server.aside', 'elanous-tool-call', { runId, toolName: name });
+              debug.log('mcp-server.aside', 'elanous-tool-result', {
+                runId, toolName: name, ok: false,
+                errorClass: rt ? 'tool_not_exposed' : 'unknown_tool',
+              });
+            } catch { /* observation must not block the caller */ }
+          }
           emitProxyCallIntent(name, ctx.origin, false, 'unknown_tool');
           return {
             ...base,
@@ -186,6 +223,10 @@ export async function handleMcpRequest(
           };
         }
         try {
+          if (asideReturn) {
+            try { debug.log('mcp-server.aside', 'elanous-tool-call', { runId, toolName: name }); }
+            catch { /* observation must not block the caller */ }
+          }
           const isMcpAgent = surface === 'mcp' && rt.id === 'agent';
           const agentArgs = isMcpAgent
             ? { ...args, run_in_background: args.run_in_background ?? true }
@@ -198,6 +239,7 @@ export async function handleMcpRequest(
           const out = await dispatchToolByName(name, agentArgs, {
             surface,
             ...(ctx.clientName ? { mcpClient: ctx.clientName } : {}),
+            ...(runId ? { runId } : {}),
             ...(agentTools ? {
               agentHostTools: agentTools.specs,
               agentCwd,
@@ -212,10 +254,22 @@ export async function handleMcpRequest(
               background: agentArgs.run_in_background === true,
             });
           }
+          if (asideReturn) {
+            const resultRecord = out && typeof out === 'object' ? out as Record<string, unknown> : {};
+            const toolOk = resultRecord.ok === false || resultRecord.isError === true
+              ? false
+              : resultRecord.ok === true ? true : null;
+            try { debug.log('mcp-server.aside', 'elanous-tool-result', { runId, toolName: name, ok: toolOk }); }
+            catch { /* observation must not block the caller */ }
+          }
           emitProxyCallIntent(name, ctx.origin, true);
           return { ...base, result: toMcpToolCallResult(out) };
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
+          if (asideReturn) {
+            try { debug.log('mcp-server.aside', 'elanous-tool-result', { runId, toolName: name, ok: false, errorClass: err instanceof Error ? err.name : 'unknown' }); }
+            catch { /* observation must not block the caller */ }
+          }
           emitProxyCallIntent(name, ctx.origin, false, msg);
           throw err;
         }