elanous 0.2.41 → 0.2.42

package/src/dashboard/skill-detection-runtime.ts

@@ -72,13 +72,25 @@ export async function detectDashboardSkillRoute(
   visibleIndex: SkillIndexEntry[],
   deps: DashboardSkillDetectionRuntimeDeps,
 ): Promise<DetectResult> {
+  const detectionStartedAt = performance.now();
   const detectKeyword = deps.detectKeyword ?? detectSkillTrigger;
   const detectWithLLM = deps.detectWithLLM ?? detectLLM;
   const parseClassifier = deps.parseClassifier ?? parseClassifierJson;
   const keywordDetection = detectKeyword(userText, visibleIndex, {});
-  if (!deps.llmFallback) return keywordDetection;
+  if (!deps.llmFallback) {
+    try {
+      debug.log('skill.router.timing', 'detection-complete', {
+        mode: 'keyword',
+        elapsedMs: Math.round((performance.now() - detectionStartedAt) * 10) / 10,
+        skillCount: visibleIndex.length,
+        candidateCount: keywordDetection.candidates.length,
+      });
+    } catch { /* observation must never delay routing */ }
+    return keywordDetection;
+  }
 
   const classify = async (prompt: string, signal?: AbortSignal): Promise<LLMClassifyResult> => {
+    const roleStartedAt = performance.now();
     const resolved = resolveRoleLlm('classify');
     const provider = llm.PROVIDERS[resolved.provider];
     if (!provider) throw new Error(`Unknown classify provider: ${resolved.provider}`);
@@ -89,21 +101,49 @@ export async function detectDashboardSkillRoute(
       provider: resolved.provider,
       source: resolved.source,
     });
-    const raw = await deps.streamLLM(
-      [{ role: 'user', content: prompt }],
-      () => {},
-      { signal, maxTokens: 120, temperature: 0, model: resolved.model, provider, usageRole: 'classify' },
-    );
+    try {
+      debug.log('skill.router.timing', 'classifier-role-ready', {
+        elapsedMs: Math.round((performance.now() - roleStartedAt) * 10) / 10,
+        provider: resolved.provider,
+        source: resolved.source,
+      });
+    } catch { /* observation must never delay routing */ }
+    const streamStartedAt = performance.now();
+    let raw: string;
+    try {
+      raw = await deps.streamLLM(
+        [{ role: 'user', content: prompt }],
+        () => {},
+        { signal, maxTokens: 120, temperature: 0, model: resolved.model, provider, usageRole: 'classify' },
+      );
+    } finally {
+      try {
+        debug.log('skill.router.timing', 'classifier-stream-complete', {
+          elapsedMs: Math.round((performance.now() - streamStartedAt) * 10) / 10,
+          provider: resolved.provider,
+        });
+      } catch { /* observation must never delay routing */ }
+    }
     return parseClassifier(raw);
   };
 
-  return detectWithLLM(userText, visibleIndex, {
-    classify,
-    keywordScoreThreshold: deps.keywordScoreThreshold,
-    llmConfidenceThreshold: deps.llmConfidenceThreshold,
-    ...(deps.signal ? { signal: deps.signal } : {}),
-    ...(deps.activeTier ? { activeTier: deps.activeTier } : {}),
-    ...(deps.fullMenuTier ? { fullMenuTier: deps.fullMenuTier } : {}),
-    ...(deps.fullMenuConfidenceThreshold != null ? { fullMenuConfidenceThreshold: deps.fullMenuConfidenceThreshold } : {}),
-  });
+  try {
+    return await detectWithLLM(userText, visibleIndex, {
+      classify,
+      keywordScoreThreshold: deps.keywordScoreThreshold,
+      llmConfidenceThreshold: deps.llmConfidenceThreshold,
+      ...(deps.signal ? { signal: deps.signal } : {}),
+      ...(deps.activeTier ? { activeTier: deps.activeTier } : {}),
+      ...(deps.fullMenuTier ? { fullMenuTier: deps.fullMenuTier } : {}),
+      ...(deps.fullMenuConfidenceThreshold != null ? { fullMenuConfidenceThreshold: deps.fullMenuConfidenceThreshold } : {}),
+    });
+  } finally {
+    try {
+      debug.log('skill.router.timing', 'detection-complete', {
+        mode: 'llm-fallback',
+        elapsedMs: Math.round((performance.now() - detectionStartedAt) * 10) / 10,
+        skillCount: visibleIndex.length,
+      });
+    } catch { /* observation must never delay routing */ }
+  }
 }

package/src/dashboard/slash-runtime/dashboard-handlers.ts

@@ -422,6 +422,21 @@ const COST_SLASH_DESCRIPTOR = buildCostSlashCommand();
 const MEMORY_SLASH_DESCRIPTOR = buildMemorySlashCommand();
 
 export interface DashboardSlashContext {
+  /** Classic /side agent commands supplied by the dashboard host. */
+  classicSidetabAgent?: {
+    loadRows(sessionId?: string): import('../../sidetab-core/model.js').SidetabRow[];
+    openAgent(agent: 'codex' | 'claude'): void;
+    runMission(agent: 'codex' | 'claude', mission: string, outputPath?: string): Promise<{
+      ok: boolean;
+      path: string;
+      firstLine?: string;
+      promptReady: boolean;
+      missionVisible: boolean;
+      promptReturned: boolean;
+      completionMarker: boolean;
+      error?: string;
+    }>;
+  };
   // Chat surface refs / mutators
   chatLines: string[];
   /** Same status-line producer the agent immediate executor uses. Absent in tests → empty. */

package/src/dashboard/turn-preamble.ts

@@ -41,6 +41,8 @@ import {
 import type { getUserConfig } from '../user-config.js';
 import { isNativeStructureEnabledForProvider, resolveActiveProvider } from '../user-config.js';
 import { measureInputLagTurnStart } from '../tui/input-lag-probe.js';
+import { resolveModelContextWindow } from '../models/context-window.js';
+import { buildInstalledSkillCatalogMessage, type InstalledSkillSummary } from './skill-catalog-preamble.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
 import { buildSelfHealthLine, type InstalledRecord, type SelfHealthErrors } from '../pty-shell/tui-run-state.js';
 import type { PtyBuildIdentity } from '../pty-shell/pty-manifest.js';
@@ -71,6 +73,12 @@ export interface DashboardTurnPreambleContext {
    *  one-liner directives (e.g. AskUserQuestion → use for tool-deny
    *  clarification). Pass `tools.map(t => t.name)` from the caller. */
   enabledTools?: readonly string[];
+  /** Installed frontmatter summaries for the stable skill-routing prompt prefix. */
+  skillCatalog?: readonly InstalledSkillSummary[];
+  /** Active model context size, when known. Unknown models use the conservative helper default. */
+  skillCatalogContextWindow?: number | null;
+  /** Runtime-selected model can differ from the configured default model. */
+  skillCatalogModelId?: string;
   /** 🪪 L1 자리 부트 카드를 싣나(`seat-boot-preamble.ts`). 대화형 TUI 호출부만 켠다 — 기본 꺼짐이라
    *  다른 호출부·시험은 셸의 `COORD_ID` 에 따라 출력이 갈리지 않는다. */
   seatBoot?: boolean | SeatBootDeps;
@@ -100,6 +108,12 @@ export interface DashboardTurnPreambleContext {
   };
 }
 
+/** Flag per-prompt system layers so the Codex Responses serializer keeps
+ *  them out of the cached `instructions` prefix (TUI-PROMPT-CACHE-PREFIX). */
+function markCacheVolatile(messages: readonly LLMMessage[]): LLMMessage[] {
+  return messages.map((m) => (m.role === 'system' ? { ...m, cacheVolatile: true } : m));
+}
+
 export function buildControllerSystemMessage(controller: string, channels?: string): LLMMessage {
   return {
     role: 'system',
@@ -172,6 +186,15 @@ function buildDashboardTurnPreambleUnmeasured(
 ): LLMMessage[] {
   const builderMs: BuilderMs | null = debug.enabled ? {} : null;
   const startedAt = builderMs === null ? 0 : performance.now();
+  // This is the first stable block in the system preamble. Its cached content changes only
+  // when the installed/visible skill list or model context budget changes.
+  const skillCatalogBuild = ctx.skillCatalog
+    ? timed(builderMs, 'skillCatalog', () => buildInstalledSkillCatalogMessage(
+      ctx.skillCatalog!,
+      ctx.skillCatalogContextWindow ?? resolveModelContextWindow(ctx.skillCatalogModelId ?? ctx.userConfig.llm.model),
+    ))
+    : null;
+  const skillCatalogSystemMsgs = skillCatalogBuild?.message ? [skillCatalogBuild.message] : [];
   // Universal preamble — surface-agnostic anchor (AGENTS.md +
   // CLAUDE.md). Spread first so the project context lands BEFORE any
   // surface-specific guidance, mirroring Claude Code's Phase 0
@@ -294,21 +317,30 @@ function buildDashboardTurnPreambleUnmeasured(
   const controllerSystemMsgs = controller
     ? timed(builderMs, 'controller', () => [buildControllerSystemMessage(controller, controlEnv.channels)])
     : [];
-  const preamble = [
+  // TUI-PROMPT-CACHE-PREFIX — only the universal anchor (AGENTS.md ·
+  // CLAUDE.md · tool discipline) is stable for the life of a session. Every
+  // other layer can change between prompts (boot card · memory · git
+  // snapshot · plan/approval mode · per-userText guidance · self health), so
+  // it is flagged `cacheVolatile`: the Codex serializer then keeps it out of
+  // `instructions` and sends it as a developer item after the cached history.
+  const preamble: LLMMessage[] = [
+    ...skillCatalogSystemMsgs,
     ...universalPreamble,
-    ...seatBootSystemMsgs,
-    ...planModeSystemMsgs,
-    ...askSystemMsgs,
-    ...approvalSystemMsgs,
-    ...sandboxSystemMsgs,
-    ...memorySystemMsgs,
-    ...gitSnapshotSystemMsgs,
-    ...surfaceSystemMsgs,
-    ...selfOpsSystemMsgs,
-    ...selfHealthSystemMsgs,
-    ...controllerSystemMsgs,
-    ...implDisciplineSystemMsgs,
-    ...concisenessSystemMsgs,
+    ...markCacheVolatile([
+      ...seatBootSystemMsgs,
+      ...planModeSystemMsgs,
+      ...askSystemMsgs,
+      ...approvalSystemMsgs,
+      ...sandboxSystemMsgs,
+      ...memorySystemMsgs,
+      ...gitSnapshotSystemMsgs,
+      ...surfaceSystemMsgs,
+      ...selfOpsSystemMsgs,
+      ...selfHealthSystemMsgs,
+      ...controllerSystemMsgs,
+      ...implDisciplineSystemMsgs,
+      ...concisenessSystemMsgs,
+    ]),
   ];
   // Capture exactly what the ACP path's getPreamble emits so we can
   // verify what codex actually sees as system prompt at turn-start.
@@ -328,7 +360,9 @@ function buildDashboardTurnPreambleUnmeasured(
       if (notificationOnlyWake) {
         preamble.push({ role: 'system', content: '[알림 전용 턴] 이것은 완료 알림을 전달한 비요청 status receipt다. 작업 요청으로 취급하지 말고 Agent 또는 SelfImplement 위임을 시작하지 않는다. 포함된 결과를 바탕으로 한 번의 간결한 상태 요약만 답하고 멈춘다. 결과가 전달되지 않았다면 결과가 아직 제공되지 않았다고 알리고 내용을 추측하지 않는다.' });
       }
-      const pendingNotifications = globalTaskNotificationQueue.drain();
+      const pendingNotifications = ctx.sessionId
+        ? globalTaskNotificationQueue.drainForParentSessionOrUnscoped(ctx.sessionId)
+        : globalTaskNotificationQueue.drain();
       taskNotificationCount = pendingNotifications.length;
       if (pendingNotifications.length === 0) {
         if (notificationOnlyWake) {
@@ -370,6 +404,7 @@ function buildDashboardTurnPreambleUnmeasured(
       hasTurnProfile: ctx.turnProfile != null,
       builderCounts: {
         universal: universalPreamble.length,
+        ...(ctx.skillCatalog ? { skillCatalog: skillCatalogSystemMsgs.length } : {}),
         seatBoot: seatBootSystemMsgs.length,
         planMode: planModeSystemMsgs.length,
         ask: askSystemMsgs.length,
@@ -390,6 +425,9 @@ function buildDashboardTurnPreambleUnmeasured(
       builderTotalMs: Math.round((performance.now() - startedAt) * 10) / 10,
       totalMessageCount: preamble.length,
       taskNotificationCount,
+      skillCatalogTokens: skillCatalogBuild?.estimatedTokens ?? 0,
+      skillCatalogBudgetTokens: skillCatalogBuild?.budgetTokens ?? 0,
+      skillCatalogMode: skillCatalogBuild?.mode ?? 'not-provided',
       totalChars: total,
       userTextPreview: ctx.userText.length > 80 ? `${ctx.userText.slice(0, 80)}…` : ctx.userText,
     });

package/src/dashboard/turn-prompt-runtime.ts

@@ -5,7 +5,7 @@ import {
   type PromptBankStore,
 } from '../prompt-bank/index.js';
 import {
-  resolveSessionTurnProfile,
+  resolveSessionTurnProfileWithHistory,
   type SessionTurnProfile,
 } from '../session-runtime/index.js';
 import type { InputSourceRef } from '../input/input-source-kind.js';
@@ -39,6 +39,7 @@ export function buildDashboardTurnPromptRuntime(
   turnId: string,
   deps: DashboardTurnPromptRuntimeDeps,
   inputSource?: InputSourceRef | null,
+  priorUserTexts: readonly string[] = [],
 ): DashboardTurnPromptRuntimeResult {
   const turnIntents = ['chat', ...classifyUserIntents(userText)];
   const promptBankInjection = deps.promptBankConfig.enabled && deps.promptBankConfig.dashboardTurns
@@ -62,8 +63,9 @@ export function buildDashboardTurnPromptRuntime(
         slots: ['context', 'tool-hint', 'user-prefix'],
       })
     : '';
-  const turnProfile = resolveSessionTurnProfile({
+  const turnProfile = resolveSessionTurnProfileWithHistory({
     userText,
+    priorUserTexts,
     chatModeState: deps.chatModeState,
     inputSource,
   });

package/src/graph-runner/graph-cli.ts

@@ -5,10 +5,10 @@ import { parse as parseYaml } from 'yaml';
 import { writeStdoutJson } from '../cli/stdout-json.js';
 import type { GraphVariantPlan } from '../self-implement/graph-variant.js';
 import { debug } from '../debug/log.js';
-import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, manageGraphRun, runGraph, type GraphRunState } from './runner.js';
+import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, manageGraphRun, runGraph, type GraphRunOptions, type GraphRunState } from './runner.js';
 
-function findGraphFile(graphId: string): string | undefined {
-  const roots = [resolve('graphs'), resolve(import.meta.dir, '../../graphs')];
+function findGraphFile(graphId: string, extraRoots: string[] = []): string | undefined {
+  const roots = [...extraRoots.map((root) => resolve(root)), resolve('graphs'), resolve(import.meta.dir, '../../graphs')];
   for (const root of roots) {
     for (const dir of [root, ...['release', 'ops'].map((part) => join(root, part))]) {
       if (!existsSync(dir)) continue;
@@ -26,7 +26,10 @@ function findGraphFile(graphId: string): string | undefined {
   return undefined;
 }
 
-export function registerGraphCommands(program: Command, runsDeps: { root?: string; processStartMs?: (pid: number) => number | null } = {}): void {
+export function registerGraphCommands(program: Command, runsDeps: {
+  root?: string; processStartMs?: (pid: number) => number | null; graphRoots?: string[];
+  runBash?: NonNullable<GraphRunOptions['deps']>['runBash'];
+} = {}): void {
   const graph = program.command('graph').description('Run a declared command graph or inspect its latest run');
   graph.command('adapt-report')
     .description('Measure recorded graph path diversity, unit calls, adaptations and landings for one goal')
@@ -333,10 +336,23 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
   graph.command('approve <graph_id> <run_id>')
     .option('--reject', 'Reject instead of approving')
     .option('--by <name>', 'Record the approver name')
-    .action((graphId: string, runId: string, opts: { reject?: boolean; by?: string }) => {
+    .action(async (graphId: string, runId: string, opts: { reject?: boolean; by?: string }) => {
       try {
-        const state = decideGraphApproval(graphId, runId, opts.reject ? 'rejected' : 'approved', opts.by);
-        console.log(`${state.graphId} ${state.runId}: ${state.pending?.decision}`);
+        // A release approval is the decision point for a live publish run. Resume its
+        // saved graph immediately so approval does not depend on a later manual tick.
+        // Resolve the release graph before recording the irreversible decision; if it
+        // is unavailable, leave the approval undecided so an operator can retry.
+        const releaseGraph = graphId === 'release-loop' ? findGraphFile(graphId, runsDeps.graphRoots) : undefined;
+        if (graphId === 'release-loop' && !releaseGraph) throw new Error('release-loop graph file not found; approval was not recorded');
+        const state = decideGraphApproval(graphId, runId, opts.reject ? 'rejected' : 'approved', opts.by, runsDeps.root);
+        if (releaseGraph) {
+          await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+          const { graphTick } = await import('./graph-tick.js');
+          const result = await graphTick(releaseGraph, { resumeRunId: runId, deps: { root: runsDeps.root, runBash: runsDeps.runBash } });
+          console.log(`${state.graphId} ${state.runId}: ${state.pending?.decision} · ${result.action} ${result.status ?? ''}`.trim());
+        } else {
+          console.log(`${state.graphId} ${state.runId}: ${state.pending?.decision}`);
+        }
       } catch (error) {
         console.error(`graph approve: ${error instanceof Error ? error.message : String(error)}`);
         process.exitCode = 1;

package/src/graph-runner/graph-tick.ts

@@ -8,10 +8,12 @@ import { peerEditRunGate } from '../nexus/api/graph-peer-edit.js';
 import { observeModelInputTokens } from '../harness/model-input-observation.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { DecisionLedger } from '../decisions/decision-ledger.js';
-import { latestGraphRun, runGraph, type GraphRunOptions, type GraphRunState } from './runner.js';
+import { latestGraphRun, listGraphRuns, runGraph, type GraphRunOptions, type GraphRunState } from './runner.js';
 
 export interface GraphTickOptions {
   startIfIdle?: boolean;
+  /** Resume this exact persisted run instead of whichever run happens to be latest. */
+  resumeRunId?: string;
   input?: unknown;
   mineDir?: string;
   deps?: GraphRunOptions['deps'] & { notify?: () => void | Promise<void>; isAlive?: (pid: number) => boolean };
@@ -96,7 +98,13 @@ export async function graphTick(path: string, options: GraphTickOptions = {}): P
     if (refusedAfterNotify) return refusedAfterNotify;
     // The run identity and executed bytes must agree with the ledger and the gate.
     if (current.graphId !== graphId) throw new Error(`graph id changed during tick: ${graphId} -> ${current.graphId}`);
-    const latest = latestGraphRun(graphId, root);
+    const latest = options.resumeRunId
+      ? listGraphRuns(root).runs.find(run => run.graphId === graphId && run.runId === options.resumeRunId) ?? null
+      : latestGraphRun(graphId, root);
+    if (options.resumeRunId && !latest) throw new Error(`graph run not found: ${graphId}/${options.resumeRunId}`);
+    if (options.resumeRunId && (latest?.status !== 'awaiting-approval' || !latest.pending?.decision)) {
+      throw new Error(`graph run is not awaiting a recorded decision: ${graphId}/${options.resumeRunId}`);
+    }
     const growthCard = latest?.growthPark
       ? (options.deps?.growthDecision?.list ?? ((filters: { status: 'all' }) => new DecisionLedger({ stateDir: root }).list(filters)))({ status: 'all' })
         .find(entry => entry.id === latest.growthPark?.decisionId && entry.refs?.includes(latest.growthPark.decisionRef))

package/src/graph-runner/runner.ts

@@ -1227,7 +1227,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         ? (lastPriorOutput as Record<string, unknown>).result : undefined;
       const inputs: Record<string, unknown> = Object.create(null);
       for (const key of contract.inputs) {
-        const value = Object.hasOwn(supplied, key) ? supplied[key] : key === 'prior' ? priorResult : previous[key];
+        const value = Object.hasOwn(supplied, key) ? supplied[key] : key === 'prior' ? (priorResult === undefined ? {} : priorResult) : previous[key];
         if (value !== undefined) inputs[key] = value;
       }
       const alreadySpent = state.path.length + (state.unitCalls ?? []).reduce((sum, call) => sum + call.steps, 0);

package/src/grok/agent-search.ts

@@ -24,6 +24,7 @@
 // Reference: https://docs.x.ai/docs/guides/tools/overview
 
 import { getGrokApiKey, refreshKeyFromCache } from '../config.js';
+import { resolveFreshGrokCredential } from './credential.js';
 import { debug } from '../debug/log.js';
 
 /** Agent Tools API endpoint (distinct from GROK_API_URL=chat/completions). */
@@ -58,6 +59,10 @@ export interface GrokAgentSearchOpts {
   /** Subscription proxy endpoint and required CLI headers. Omit for the metered xAI API. */
   baseUrl?: string;
   headers?: Record<string, string>;
+  /** Opt-in credential order for search callers; unset preserves the direct API-key behavior. */
+  credentialPreference?: 'api_key';
+  /** Model used only when resolving a fallback subscription credential. */
+  credentialModel?: string;
 }
 
 export interface GrokCitation {
@@ -89,7 +94,11 @@ export async function grokAgentSearch(
   query: string,
   opts: GrokAgentSearchOpts = {},
 ): Promise<GrokAgentSearchResult> {
-  const apiKey = opts.apiKey ?? getGrokApiKey();
+  const credential = opts.credentialPreference
+    ? resolveFreshGrokCredential({ prefer: opts.credentialPreference, ...(opts.credentialModel ? { model: opts.credentialModel } : {}) })
+    : null;
+  if (credential) debug.log('grok.agent-search', 'credential-selected', { kind: credential.kind, source: credential.source });
+  const apiKey = opts.apiKey ?? credential?.token ?? getGrokApiKey();
   if (!apiKey) return { ok: false, status: 0, text: '', citations: [], error: 'missing-api-key' };
 
   const fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
@@ -109,13 +118,14 @@ export async function grokAgentSearch(
 
   let res: Response;
   try {
-    const endpoint = opts.baseUrl
-      ? `${opts.baseUrl.replace(/\/$/, '').replace(/\/responses$/, '')}/responses`
+    const baseUrl = opts.baseUrl ?? credential?.baseUrl;
+    const endpoint = baseUrl
+      ? `${baseUrl.replace(/\/$/, '').replace(/\/responses$/, '')}/responses`
       : GROK_RESPONSES_URL;
     res = await fetchImpl(endpoint, {
       method: 'POST',
       signal: ac.signal,
-      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, ...opts.headers },
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, ...credential?.headers, ...opts.headers },
       body: JSON.stringify({
         model,
         input,

package/src/grok/credential.ts

@@ -1,11 +1,12 @@
-// ── Grok 자격 해석 — ⭐ **구독(OAuth)이 언제나 1순위, API 키는 2순위** ──
+// ── Grok 자격 해석 — ⭐ 기본은 구독 1순위, 검색은 명시적으로 API 키 우선 ──
 //
 // 대표 지시 2026-08-13: *"엘라누스 안에서 grok 이 구독으로 도는 경우도 진행해야 합니다.
 // 구독이 있는 경우 api key 는 항상 2순위로 되게 해주세요."*
 //
-// ⛔ **왜 이 파일이 «하나»여야 하나** — elanous 에는 grok 이 나가는 경로가 둘이다:
+// ⛔ **왜 이 파일이 «하나»여야 하나** — elanous 에는 grok 이 나가는 경로가 여럿이다:
 //   ⑴ ACP 백엔드   `grok agent stdio` (자식 바이너리가 auth.json 을 직접 읽는다)
 //   ⑵ LLM 프로바이더 `streamChat` (elanous 가 Bearer 를 «직접» 실어 보낸다)
+//   ⑶ 검색          검색만 `prefer: 'api_key'` 로 비용 출처를 분리하고, 키가 없으면 구독으로 폴백한다
 // 예전엔 ⑴만 구독을 강제(env 스크럽)하고 ⑵는 무조건 API 키였다. 규칙이 갈리면
 // 「구독을 켰는데 지갑이 열리는」 사고가 난다. ⇒ 두 경로가 이 파일 하나를 읽는다.
 //
@@ -29,6 +30,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { keyFromCacheOrEnv } from '../config.js';
 
 /** 구독 프록시 베이스. ⛔ `api.x.ai` 가 «아니다** — 그쪽은 API 키(토큰 과금) 전용. */
 export const GROK_SUBSCRIPTION_BASE_URL = 'https://cli-chat-proxy.grok.com/v1';
@@ -312,11 +314,30 @@ function readGrokCredential(opts: {
   home?: string;
   model?: string;
   cliVersion?: string;
+  /** Search surfaces may prefer metered API credentials; all other callers retain subscription-first. */
+  prefer?: 'api_key';
   /** 구독을 «건너뛴다** — 401 을 맞은 뒤 호출자가 강등할 때만 쓴다. */
   skipSubscription?: boolean;
 } = {}): GrokCredential | null {
   const env = opts.env ?? process.env;
 
+  const readApiKey = (cacheFirst = false): GrokCredential | null => {
+    for (const name of ['XAI_API_KEY', 'GROK_API_KEY', 'GROK_CODE_XAI_API_KEY'] as const) {
+      const useCache = cacheFirst && (!opts.env || opts.env === process.env);
+      const value = useCache ? keyFromCacheOrEnv(name) : env[name];
+      if (value && value.length > 0) {
+        const source = env[name] === value ? name : `${name.toLowerCase()}-cache`;
+        return { kind: 'api_key', baseUrl: GROK_API_BASE_URL, token: value, headers: {}, source };
+      }
+    }
+    return null;
+  };
+
+  if (opts.prefer === 'api_key') {
+    const apiKey = readApiKey(true);
+    if (apiKey) return apiKey;
+  }
+
   if (opts.skipSubscription !== true) {
     const sub = readSubscriptionToken(grokAuthFilePath(opts.home));
     if (sub) {
@@ -335,18 +356,12 @@ function readGrokCredential(opts: {
     }
   }
 
-  // 2순위 — API 키(토큰 과금). 이름 순서는 xAI 문서 관례를 따른다.
-  for (const name of ['XAI_API_KEY', 'GROK_API_KEY', 'GROK_CODE_XAI_API_KEY'] as const) {
-    const value = env[name];
-    if (value && value.length > 0) {
-      return { kind: 'api_key', baseUrl: GROK_API_BASE_URL, token: value, headers: {}, source: name };
-    }
-  }
-  return null;
+  // Default callers keep subscription-first. Search surfaces opt into API-key-first above.
+  return readApiKey();
 }
 
 /** Read-only credential check for synchronous provider availability. Never refreshes or calls the network. */
-export function peekGrokCredential(opts: { home?: string; model?: string } = {}): GrokCredential | null {
+export function peekGrokCredential(opts: { home?: string; model?: string; prefer?: 'api_key' } = {}): GrokCredential | null {
   return readGrokCredential(opts);
 }
 
@@ -607,6 +622,8 @@ export interface ResolveFreshGrokOpts {
   model?: string;
   cliVersion?: string;
   skipSubscription?: boolean;
+  /** Search surfaces may prefer API-key billing; omitted callers remain subscription-first. */
+  prefer?: 'api_key';
   /** ⛔ 테스트 심 — 실 바이너리 없이 계약을 문다. */
   execImpl?: (cmd: string, args: string[], timeoutMs: number) => void;
   now?: () => number;

package/src/harness/harness-pod-dispatch.ts

@@ -107,7 +107,29 @@ export function podOrchestrateArgs(input: HarnessPodDispatchInput, goalFile: str
   ];
 }
 
-type PodDispatchDeps = { run?: (cmd: string, args: readonly string[], env: NodeJS.ProcessEnv) => number | null; readFile?: (path: string) => string; cwd?: string; spawnChild?: typeof spawn; onOutput?: (text: string) => void; recordRunLedgerEntry?: typeof appendRunLedgerEntry; nowMs?: number };
+type PodDispatchExitObservation = {
+  status: number | null;
+  parentSignalReceived: NodeJS.Signals | null;
+  parentSignalReceivedAt: string | null;
+  parentSignalLastReceived?: NodeJS.Signals | null;
+  parentSignalLastReceivedAt?: string | null;
+  signalDelivery: 'requested' | 'child-not-running' | 'kill-failed' | null;
+  signalDeliveryFor?: NodeJS.Signals | null;
+  orchestratorProcessSignal: NodeJS.Signals | null;
+  observedAt: string;
+};
+type PodDispatchRunResult = number | null | PodDispatchExitObservation;
+type PodDispatchDeps = { run?: (cmd: string, args: readonly string[], env: NodeJS.ProcessEnv) => PodDispatchRunResult; readFile?: (path: string) => string; cwd?: string; spawnChild?: typeof spawn; onOutput?: (text: string) => void; recordRunLedgerEntry?: typeof appendRunLedgerEntry; nowMs?: number };
+
+export function classifyPodDispatchSignalSource(observation: Pick<PodDispatchExitObservation, 'parentSignalReceived' | 'signalDelivery' | 'orchestratorProcessSignal' | 'status'> & Partial<Pick<PodDispatchExitObservation, 'parentSignalLastReceived' | 'signalDeliveryFor'>>): 'parent-signal-forward-requested' | 'orchestrator-process-signaled' | 'unknown-143' | 'unknown-signal-exit' | 'non-signal-exit' {
+  const lastSignal = observation.parentSignalLastReceived ?? observation.parentSignalReceived;
+  const deliveryFor = observation.signalDeliveryFor ?? lastSignal;
+  if (lastSignal && observation.signalDelivery === 'requested' && deliveryFor === lastSignal) return 'parent-signal-forward-requested';
+  if (observation.orchestratorProcessSignal) return 'orchestrator-process-signaled';
+  if (observation.status === 143) return 'unknown-143';
+  if (observation.status === 130 || observation.status === null) return 'unknown-signal-exit';
+  return 'non-signal-exit';
+}
 
 /** Default Pod source clones origin HEAD. Never infer its file occupation from an unrelated worktree. */
 function defaultPodSourceHeadAt(root: string): string | undefined {
@@ -294,39 +316,83 @@ export function dispatchHarnessOnPod(input: HarnessPodDispatchInput, deps: PodDi
     childLlmProvider: input.childLlmProvider ?? null, childLlmModel: input.childLlmModel ?? null,
     goalChars, ...(input.entrance === 'cli-harness-ask' ? { goalPath: input.input } : {}),
   });
-  const run = deps.run ?? ((cmd: string, a: readonly string[], childEnv: NodeJS.ProcessEnv) => new Promise<number>((resolveStatus) => {
+  const run = deps.run ?? ((cmd: string, a: readonly string[], childEnv: NodeJS.ProcessEnv) => new Promise<PodDispatchExitObservation>((resolveStatus) => {
     const ownsOutput = Boolean(deps.onOutput);
     const child = (deps.spawnChild ?? spawn)(cmd, [...a], {
-      stdio: ownsOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-      env: childEnv,
+      stdio: ownsOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit', env: childEnv,
     });
     child.stdout?.setEncoding('utf8');
     child.stdout?.on('data', (chunk: string) => { process.stdout.write(chunk); deps.onOutput?.(chunk); });
     if (ownsOutput) forwardChildStderr(child.stderr);
-    let forwarded: NodeJS.Signals | undefined;
+    let parentSignalReceived: NodeJS.Signals | undefined;
+    let parentSignalReceivedAt: string | undefined;
+    let parentSignalLastReceived: NodeJS.Signals | undefined;
+    let parentSignalLastReceivedAt: string | undefined;
+    let signalDelivery: PodDispatchExitObservation['signalDelivery'];
+    let signalDeliveryFor: NodeJS.Signals | undefined;
     const forward = (signal: NodeJS.Signals) => {
-      forwarded = signal;
-      if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+      const receivedAt = new Date().toISOString();
+      parentSignalReceived ??= signal;
+      parentSignalReceivedAt ??= receivedAt;
+      parentSignalLastReceived = signal;
+      parentSignalLastReceivedAt = receivedAt;
+      signalDeliveryFor = signal;
+      if (child.exitCode !== null || child.signalCode !== null) {
+        signalDelivery = 'child-not-running';
+        return;
+      }
+      try { signalDelivery = child.kill(signal) ? 'requested' : 'kill-failed'; }
+      catch { signalDelivery = 'kill-failed'; }
     };
     const onTerm = () => forward('SIGTERM');
     const onInt = () => forward('SIGINT');
     process.on('SIGTERM', onTerm);
     process.on('SIGINT', onInt);
     const cleanup = () => { process.off('SIGTERM', onTerm); process.off('SIGINT', onInt); };
-    child.once('error', () => { cleanup(); resolveStatus(1); });
-    child.once('close', (code, signal) => { cleanup(); resolveStatus(code ?? ((signal ?? forwarded) === 'SIGINT' ? 130 : 143)); });
+    child.once('error', () => {
+      cleanup();
+      resolveStatus({ status: 1, parentSignalReceived: parentSignalReceived ?? null, parentSignalReceivedAt: parentSignalReceivedAt ?? null,
+        parentSignalLastReceived: parentSignalLastReceived ?? null, parentSignalLastReceivedAt: parentSignalLastReceivedAt ?? null,
+        signalDelivery: signalDelivery ?? null, signalDeliveryFor: signalDeliveryFor ?? null,
+        orchestratorProcessSignal: null, observedAt: new Date().toISOString() });
+    });
+    child.once('close', (code, signal) => {
+      cleanup();
+      resolveStatus({
+        status: code ?? ((signal ?? parentSignalReceived) === 'SIGINT' ? 130 : 143),
+        parentSignalReceived: parentSignalReceived ?? null,
+        parentSignalReceivedAt: parentSignalReceivedAt ?? null,
+        parentSignalLastReceived: parentSignalLastReceived ?? null,
+        parentSignalLastReceivedAt: parentSignalLastReceivedAt ?? null,
+        signalDelivery: signalDelivery ?? null,
+        signalDeliveryFor: signalDeliveryFor ?? null,
+        orchestratorProcessSignal: signal ?? null,
+        observedAt: new Date().toISOString(),
+      });
+    });
   }));
+  const recordExit = (result: PodDispatchRunResult): number => {
+    const observation = typeof result === 'number' || result === null
+      ? { status: result, parentSignalReceived: null, parentSignalReceivedAt: null, parentSignalLastReceived: null, parentSignalLastReceivedAt: null,
+        signalDelivery: null, signalDeliveryFor: null, orchestratorProcessSignal: null, observedAt: new Date().toISOString() }
+      : result;
+    debug.log('harness.substrate', 'dispatch-pod-exit', {
+      entrance: input.entrance,
+      reporterSeat: input.seat ?? process.env.ELANOUS_HARNESS_SEAT ?? null,
+      reporterCommand: input.entrance === 'cli-harness-ask' ? 'harness ask' : 'harness say',
+      ...observation, signalSource: classifyPodDispatchSignalSource(observation),
+    });
+    return observation.status ?? 1;
+  };
   const cleanup = () => { if (tempDir) rmSync(tempDir, { recursive: true, force: true }); };
   try {
     const status = run(process.execPath, args, env);
-    if (typeof status === 'number' || status === null) {
+    if (typeof status === 'number' || status === null || !('then' in status)) {
       cleanup();
-      debug.log('harness.substrate', 'dispatch-pod-exit', { entrance: input.entrance, status });
-      return status ?? 1;
+      return recordExit(status);
     }
-    return status.then((code) => {
-      debug.log('harness.substrate', 'dispatch-pod-exit', { entrance: input.entrance, status: code });
-      return code;
+    return status.then((result) => {
+      return recordExit(result);
     }).finally(cleanup);
   } catch (error) {
     cleanup();