elanous 0.2.40 → 0.2.42

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')
@@ -258,10 +261,31 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
           const { createScheduleSource } = await import('../workflow-runtime/triggers/schedule-source.js');
           const graphFile = resolve(file);
           const source = createScheduleSource();
+          const graphDocument = parseYaml(readFileSync(graphFile, 'utf8')) as { graph_id?: string; loop?: { trigger?: { events?: string[] } } };
+          const cutEventSubscribed = graphDocument.graph_id === 'release-loop'
+            && graphDocument.loop?.trigger?.events?.includes('release.cut.due') === true;
           // The CLI tick callback is the graph counterpart of the workflow scheduler's onEmit.
           const onScheduledTick = async () => {
             try {
               const { notifyGraphEvents } = await import('./graph-notify.js');
+              if (cutEventSubscribed) {
+                const { emitDueReleaseCutEvents } = await import('../release-loop/release-schedule.js');
+                const { runUnattendedRelease } = await import('../../scripts/release-loop/unattended-release.js');
+                try {
+                  await emitDueReleaseCutEvents(new Date().toISOString(), async event => {
+                    const fired = await runUnattendedRelease({ version: event.version, triggerEvent: event });
+                    await notifyGraphEvents();
+                    if (fired.state?.status === 'failed') console.error(`graph tick: ${fired.state.runId}: failed`);
+                  });
+                } catch (error) {
+                  debug.log('graph.runner', 'cut-event-failed', { file: graphFile, error: error instanceof Error ? error.message : String(error) });
+                  console.error(`graph cut event: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                const resumed = await graphTick(graphFile, { deps: { notify: async () => { await notifyGraphEvents(); } } });
+                if (resumed.status === 'refused') console.error(`graph tick: refused: ${resumed.reason}`);
+                else if (resumed.status === 'failed') console.error(`graph tick: ${resumed.runId}: failed`);
+                return;
+              }
               const result = await graphTick(graphFile, { startIfIdle: true, deps: { notify: async () => { await notifyGraphEvents(); } } });
               if (result.status === 'refused') console.error(`graph tick: refused: ${result.reason}`);
               else if (result.status === 'failed') console.error(`graph tick: ${result.runId}: failed`);
@@ -312,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/in-process-registry.ts

@@ -0,0 +1,37 @@
+/** A run-scoped registry keeps in-process graph effects out of YAML and shell recipes. */
+export interface InProcessHandlerContext {
+  readonly graphId: string;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly input: unknown;
+  readonly outputs: Readonly<Record<string, unknown>>;
+}
+
+export interface InProcessHandlerResult {
+  readonly ok: boolean;
+  /** Named edge outcome from the graph's declared map. */
+  readonly outcome: string;
+  readonly evidence?: Readonly<Record<string, unknown>>;
+  readonly error?: string;
+}
+
+export type InProcessHandler = (context: InProcessHandlerContext) =>
+  InProcessHandlerResult | Promise<InProcessHandlerResult>;
+
+export type InProcessHandlerRegistry = Readonly<Record<string, InProcessHandler>>;
+
+function inProcessHandlerName(recipe: string): string | undefined {
+  if (!recipe.startsWith('handler:')) return undefined;
+  const name = recipe.slice('handler:'.length);
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`invalid in-process handler recipe: ${recipe}`);
+  return name;
+}
+
+export function requireInProcessHandler(recipe: string, nodeId: string,
+  registry: InProcessHandlerRegistry | undefined): InProcessHandler | undefined {
+  const name = inProcessHandlerName(recipe);
+  if (name === undefined) return undefined;
+  const handler = registry && Object.hasOwn(registry, name) ? registry[name] : undefined;
+  if (typeof handler !== 'function') throw new Error(`unknown in-process handler for ${nodeId}: ${name}`);
+  return handler;
+}

package/src/graph-runner/runner.ts

@@ -26,6 +26,7 @@ import { createGraphVariant, type GraphVariantPlan } from '../self-implement/gra
 import { psProcessStartMs, START_TOLERANCE_MS } from '../harness/harness-stop.js';
 import { executeBashNode } from '../workflow-runtime/nodes/bash.js';
 import { executeClassifyNode } from '../workflow-runtime/nodes/classify.js';
+import { requireInProcessHandler, type InProcessHandlerRegistry } from './in-process-registry.js';
 import { interpolate } from '../workflow-runtime/variables.js';
 import type { BashNode, ClassifyNode, NodeExecContext, NodeOutput, WorkflowDeps } from '../workflow-runtime/types.js';
 import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeGatePodPool, releaseResumeGateShardReroute, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride, type GatePodPoolOverride, type GateShardRerouteOverride } from '../../scripts/release-loop/resume.js';
@@ -257,7 +258,7 @@ export interface GraphRunOptions {
   releaseCommandSource?: { root: string; cutTip: string; git?: (args: string[]) => string };
   /** Optional per-run Bloom edge policy hook. */
   researchEdgeDecisionRegistry?: ResearchEdgeDecisionRegistry;
-  deps?: { root?: string; runBash?: BashRun; callLLM?: (prompt: string) => Promise<string>; log?: (event: string, data: Record<string, unknown>) => void; beforeNode?: () => void; processStartMs?: (pid: number) => number | null; growthProposer?: GrowthProposer; growthLLM?: (prompt: string) => Promise<string>; classifyGrowthRecipe?: (node: GraphNodeSpec, resolved: { command?: string; approval?: string }) => GrowthRecipeEffect; growthDecision?: GrowthDecisionDeps & { list?: (filters: { status: 'all' }) => DecisionEntry[] } };
+  deps?: { root?: string; runBash?: BashRun; callLLM?: (prompt: string) => Promise<string>; log?: (event: string, data: Record<string, unknown>) => void; beforeNode?: () => void; processStartMs?: (pid: number) => number | null; growthProposer?: GrowthProposer; growthLLM?: (prompt: string) => Promise<string>; classifyGrowthRecipe?: (node: GraphNodeSpec, resolved: { command?: string; approval?: string }) => GrowthRecipeEffect; growthDecision?: GrowthDecisionDeps & { list?: (filters: { status: 'all' }) => DecisionEntry[] }; inProcessHandlers?: InProcessHandlerRegistry };
 }
 
 /** The command directory must itself be the checkout at the cut tip. */
@@ -756,6 +757,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   for (const node of graph.nodes) {
     if (node.kind === 'classify' && node.recipe !== 'none') throw new Error(`classify node cannot execute a recipe: ${node.nodeId}`);
     if (node.recipe === 'none') continue;
+    if (node.recipe.startsWith('handler:')) {
+      requireInProcessHandler(node.recipe, node.nodeId, options.deps?.inProcessHandlers);
+      continue;
+    }
     const resolved = resolveNodeRecipe(node, recipes, catalogRoles);
     // Harness loop recipes are labels the self-implement harness dispatches by node id (most are outside the
     // node catalog — graph-catalog.test.ts); a planned loop never executes them, and a real run is refused above.
@@ -1107,6 +1112,31 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     let commandFailureReason: string | undefined;
     let output: unknown;
     const waiving = options.releaseWaiver?.nodeId === current && waivedRecord !== undefined;
+    const inProcessHandler = requireInProcessHandler(node.recipe, current, options.deps?.inProcessHandlers);
+    let handlerExecuted = false;
+    if (inProcessHandler && !waiving && !state.dryRun && !resumingCompleted) {
+      const outputs: Record<string, unknown> = Object.create(null);
+      for (const previous of state.nodes) outputs[previous.nodeId] = lastJsonObject(previous.output) ?? previous.output ?? null;
+      handlerExecuted = true;
+      debug.log('graph.run', 'handler-dispatch', { graphId, runId, nodeId: current, recipe: node.recipe });
+      try {
+        const result = await inProcessHandler({ graphId, runId, nodeId: current, input: state.input ?? null, outputs });
+        if (!result || typeof result.ok !== 'boolean' || typeof result.outcome !== 'string' || !result.outcome.trim())
+          throw new Error(`invalid in-process handler result: ${current}`);
+        output = JSON.stringify({ ...(result.evidence === undefined ? {} : { evidence: result.evidence }), outcome: result.outcome });
+        ok = result.ok;
+        exit = ok ? 0 : 1;
+        error = result.error;
+      } catch (cause) {
+        ok = false;
+        exit = 1;
+        error = redactCredentials(cause instanceof Error ? cause.message : String(cause));
+        output = JSON.stringify({ outcome: 'fail', error });
+      }
+      debug.log('graph.run', 'handler-result', { graphId, runId, nodeId: current, recipe: node.recipe, ok,
+        outcome: lastJsonObject(output)?.outcome ?? null, ...(error ? { error } : {}) });
+      state.executed++;
+    }
     if (command && !waiving && (!approval || state.dryRun || ok) && (!state.dryRun || command.dry_run_command) && !resumingCompleted) {
       const outputs: Record<string, unknown> = Object.create(null);
       // 구조 산출(마지막 JSON 줄)이 있으면 그것을, 없으면 원문을 준다 — 다음 노드가 판단을 «값»으로 받는다.
@@ -1197,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);
@@ -1345,7 +1375,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         message: failureMessage,
         stage: units.has(current) ? 'unit-invocation' : command ? 'command-execution' : prompt ? 'prompt-execution' : 'node-execution',
       };
-      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && ((!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (node.kind === 'classify' && !state.dryRun) || unitExecuted), ...((waiving || harnessLoopRoute || units.has(current) || ((command || prompt || approval || node.kind === 'classify') && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}),
+      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && (handlerExecuted || (!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (node.kind === 'classify' && !state.dryRun) || unitExecuted), ...((waiving || harnessLoopRoute || units.has(current) || handlerExecuted || ((command || prompt || approval || node.kind === 'classify') && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}),
         ...(failure ? { reason: failure.message, failure } : {}), ...(commandFailureReason && !failure ? { reason: commandFailureReason } : {}),
         ...(waiving ? { waiver: { reason: options.releaseWaiver!.reason, at: nodeEndedAt, ...(options.releaseWaiver!.unmeasured === undefined ? {} : { unmeasured: options.releaseWaiver!.unmeasured }), original: { exit: waivedRecord!.exit, ...(waivedRecord!.output === undefined ? {} : { output: waivedRecord!.output }), ...(waivedRecord!.error === undefined ? {} : { error: waivedRecord!.error }) } } } : {}),
         ...(approval && state.pending ? { ...(state.pending.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending.decidedAt } : {}),
@@ -1359,7 +1389,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       delete state.pending;
       delete state.approvalSourceHash;
     }
-    const reported: unknown = waiving || harnessLoopRoute || units.has(current) || (prompt && !state.dryRun) || (command && (!state.dryRun || command.dry_run_command)) ? lastJsonObject(resumingCompleted ? completed?.output : output)?.outcome : undefined;
+    const reported: unknown = waiving || harnessLoopRoute || units.has(current) || handlerExecuted || (resumingCompleted && inProcessHandler) || (prompt && !state.dryRun) || (command && (!state.dryRun || command.dry_run_command)) ? lastJsonObject(resumingCompleted ? completed?.output : output)?.outcome : undefined;
     const namedOutcome: string | undefined = typeof reported === 'string' ? reported : undefined;
     if (!options.quiet) console.error(`[graph] ${current} ${ok ? 'ok' : 'fail'} (${seconds.toFixed(2)}s)`);
     const nodeFailure = state.nodes.at(-1)?.nodeId === current ? state.nodes.at(-1)?.failure : undefined;

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/grounding/ref-index.ts

@@ -151,6 +151,25 @@ export function buildReferenceCard(
   };
 }
 
+/**
+ * Cards for a whole registry/discovery batch. Read-only: no writes anywhere.
+ * Non-local kinds and unreadable paths are skipped — one bad source must not
+ * sink the batch. Pure value out.
+ */
+export function buildReferenceCardsForRegistry(
+  sources: readonly GroundingSource[],
+  fs: RefIndexFs = nodeRefIndexFs,
+  limits: Partial<RefIndexLimits> = {},
+): ReferenceCard[] {
+  const cards: ReferenceCard[] = [];
+  for (const source of sources) {
+    if ((source.kind !== 'local-repo' && source.kind !== 'local-docs') || !source.path) continue;
+    if (fs.mtimeMs(source.path) === undefined) continue;
+    cards.push(buildReferenceCard(source, fs, limits));
+  }
+  return cards;
+}
+
 function receivedAtOf(source: GroundingSource, fs: RefIndexFs, root: string): string | undefined {
   if (source.kind === 'local-repo') {
     const commit = fs.lastCommitAt(root);

package/src/grounding/sources-cli.ts

@@ -6,6 +6,7 @@ import type { Command } from 'commander';
 import { homedir } from 'node:os';
 import { basename } from 'node:path';
 import { exportMirrorManifest } from './mirror-export.js';
+import { buildReferenceCardsForRegistry, nodeRefIndexFs } from './ref-index.js';
 import {
   addGroundingSource,
   discoverReferenceSources,
@@ -83,8 +84,15 @@ export function registerGroundingSourcesCli(program: Command): void {
     .description('~/source/ref 와 ~/docs/ref 후보를 찾는다(등록하지 않는다)')
     .option('--json', 'JSON 출력')
     .option('--home <dir>', '홈 디렉터리(기본: os homedir)')
-    .action((opts: { json?: boolean; home?: string }) => {
+    .option('--ref-index', 'local-repo·local-docs 후보를 L0 카드 ⊕ L1 목록으로 색인해 JSON 으로 낸다(읽기 전용 · 쓰기 0)')
+    .action((opts: { json?: boolean; home?: string; refIndex?: boolean }) => {
       const found = discoverReferenceSources(opts.home ?? homedir());
+      if (opts.refIndex) {
+        // 읽기 전용: 카드는 stdout 으로만 낸다 — `<stateDir>/ref-index.jsonl` 원장
+        // (⊕ BM25 낱말 색인 ⊕ 보조 서버 부하 규칙)은 다음 조각의 몫.
+        printJson(buildReferenceCardsForRegistry(found, nodeRefIndexFs));
+        return;
+      }
       if (opts.json) printJson(found);
       else if (found.length === 0) console.log('(none)');
       else for (const source of found) console.log(formatSource(source));