elanous 0.2.37 → 0.2.40

package/src/graph-wizard/mission-compose.ts

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { validateGraphYaml } from '../nexus/api/graph-kinds.js';
+import { edgeMapOf, parseGraphTemplateYaml, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { resolveGraphUnit } from '../self-implement/graph-unit-resolver.js';
+import { inspectPipelineGraph } from '../self-implement/pipeline-shape.js';
+import { debug } from '../debug/log.js';
+import { generateGraphFromPrompt, type GraphWizardDeps } from './generate.js';
+import type { CompletionKind, CompositionSelection } from '../task-agent/task-hand.js';
+
+export interface MissionComposeInput {
+  text: string;
+  completion: CompletionKind;
+  root: string;
+  ledgerPath: string;
+  cardId: string;
+  standard: CompositionSelection;
+}
+
+/** The LLM may choose the order of existing verb calls, but not their authority or the hand's launcher. */
+export function missionGraphIssues(yaml: string, baseYaml: string, root: string, generatedPath?: string): string[] {
+  const checked = validateGraphYaml('harness', yaml);
+  const issues = checked.errors.map(error => typeof error === 'string' ? error : JSON.stringify(error));
+  const parsed = parseGraphTemplateYaml(yaml);
+  const base = parseGraphTemplateYaml(baseYaml);
+  issues.push(...parsed.errors.map(error => `${error.path}: ${error.message}`));
+  if (!parsed.template || !base.template) return issues;
+  const graph = parsed.template;
+  const standard = base.template;
+  const raw = parseYaml(yaml) as Record<string, unknown>;
+  const baseRaw = parseYaml(baseYaml) as Record<string, unknown>;
+  if (raw.launcher !== baseRaw.launcher) issues.push('I6: 표준 launcher 제어를 바꿀 수 없다');
+  for (const key of new Set([...Object.keys(baseRaw), ...Object.keys(raw)])) {
+    if (['graph_id', 'loop', 'nodes', 'edges'].includes(key)) continue;
+    if (JSON.stringify(raw[key]) !== JSON.stringify(baseRaw[key])) issues.push(`I6: 표준 제어 ${key} 변경 금지`);
+  }
+  if (raw.entry_node !== baseRaw.entry_node) issues.push('I6: 표준 진입 노드를 바꿀 수 없다');
+  if (JSON.stringify(raw.terminal_nodes) !== JSON.stringify(baseRaw.terminal_nodes)) issues.push('I4: 표준 종료 노드를 바꿀 수 없다');
+  const baseLoop = baseRaw.loop as { trigger?: unknown } | undefined;
+  const loop = raw.loop as { trigger?: unknown } | undefined;
+  if (JSON.stringify(loop?.trigger) !== JSON.stringify(baseLoop?.trigger)) issues.push('I6: 표준 트리거 변경 금지');
+  const rawNodes = Array.isArray(raw.nodes) ? raw.nodes as Array<Record<string, unknown>> : [];
+  const baseNodes = Array.isArray(baseRaw.nodes) ? baseRaw.nodes as Array<Record<string, unknown>> : [];
+  for (const node of rawNodes) {
+    const original = baseNodes.find(candidate => candidate.call && candidate.call === node.call)
+      ?? baseNodes.find(candidate => candidate.node_id === node.node_id && candidate.kind === 'gate');
+    if (!original) continue;
+    const keys = new Set([...Object.keys(node), ...Object.keys(original)]);
+    for (const key of keys) {
+      if (key === 'node_id' || key === 'max_visits') continue;
+      if (JSON.stringify(node[key]) !== JSON.stringify(original[key])) issues.push(`I6: ${String(node.node_id)} 권한 ${key} 변경 금지`);
+    }
+  }
+  const rawEdges = Array.isArray(raw.edges) ? raw.edges as Array<Record<string, unknown>> : [];
+  if (rawEdges.some(edge => Object.keys(edge).some(key => !['from', 'to', 'on', 'map'].includes(key))))
+    issues.push('I6: 간선 조건·폴백 권한 추가 금지');
+  const allowed = new Map(standard.nodes.filter(n => n.kind === 'subgraph' && n.call?.startsWith('verb-')).map(n => [n.call!, n]));
+  const standardById = new Map(standard.nodes.map(n => [n.nodeId, n]));
+  const seenCalls = new Set<string>();
+  for (const node of graph.nodes) {
+    const original = standardById.get(node.nodeId);
+    if (!original && /(?:merge|publish|send|pay|charge|deploy|release)/i.test(`${node.nodeId} ${node.call ?? ''}`))
+      issues.push(`I5: 외부 효과 동사 추가 금지 (${node.nodeId})`);
+    if (original?.kind === 'gate' && node.kind === 'gate'
+      && JSON.stringify(node) === JSON.stringify(original)) continue;
+    const known = node.kind === 'subgraph' && node.call ? allowed.get(node.call) : undefined;
+    if (!known || node.recipe !== 'none' || node.maxVisits > known.maxVisits
+      || JSON.stringify(node.contract) !== JSON.stringify(known.contract)
+      || JSON.stringify(node.budget) !== JSON.stringify(known.budget)
+      || node.skipWhen !== undefined || node.callEntry !== undefined)
+      issues.push(`권한 표: ${node.nodeId} 는 허용된 동사 단위가 아니다`);
+    if (node.call) seenCalls.add(node.call);
+  }
+  for (const call of allowed.keys()) if (!seenCalls.has(call)) issues.push(`권한 표: 표준 동사 단위 ${call} 누락`);
+  for (const required of standard.nodes.filter(n => n.kind === 'gate' || ['gate', 'freeze-check', 'review'].includes(n.nodeId))) {
+    if (!graph.nodes.some(n => n.nodeId === required.nodeId && JSON.stringify(n) === JSON.stringify(required))) issues.push(`권한 표: 보호 노드 ${required.nodeId} 누락 또는 변경`);
+  }
+  for (const terminal of standard.terminalNodes) if (!graph.terminalNodes.includes(terminal)) issues.push(`I4: 종료 ${terminal} 누락`);
+  const edges = edgeMapOf(graph);
+  issues.push(...inspectPipelineGraph(edges, graph.entryNode).map(defect => `I4: ${JSON.stringify(defect)}`));
+  for (const node of graph.nodes) {
+    const reachable = new Set<string>();
+    const queue = [node.nodeId];
+    while (queue.length) {
+      const id = queue.shift()!;
+      if (reachable.has(id)) continue;
+      reachable.add(id);
+      queue.push(...(edges[id] ?? []));
+    }
+    if (![...reachable].some(id => graph.terminalNodes.includes(id))) issues.push(`I4: ${node.nodeId} 에서 종료 불가`);
+  }
+  const mergeNodes = graph.nodes.filter(n => n.nodeId.includes('merge') || n.call?.includes('merge'));
+  for (const merge of mergeNodes) {
+    const prerequisites = ['gate', 'freeze-check', 'review'];
+    const walk = (id: string, seen: Set<string>, met: Set<string>): void => {
+      if (id === merge.nodeId) {
+        for (const required of prerequisites) if (!met.has(required)) issues.push(`I1~I3: merge 앞 ${required} 없음`);
+        return;
+      }
+      if (seen.has(id)) return;
+      const nextMet = new Set(met);
+      if (prerequisites.includes(id)) nextMet.add(id);
+      const nextSeen = new Set(seen).add(id);
+      for (const target of edges[id] ?? []) walk(target, nextSeen, nextMet);
+    };
+    walk(graph.entryNode, new Set(), new Set());
+  }
+  for (const node of graph.nodes.filter(n => n.kind === 'subgraph')) {
+    if (!node.call || !allowed.has(node.call)) continue;
+    try {
+      const canonical = resolveGraphUnit(node.call, join(root, 'graphs/work', 'generated.yaml'));
+      const actual = resolveGraphUnit(node.call, generatedPath ?? join(root, 'graphs/work', 'generated.yaml'));
+      const unit = actual.template;
+      if (actual.hash !== canonical.hash || `${unit.graphId}@${unit.version}` !== node.call || !unit.unit ||
+        JSON.stringify(unit.unit.inputs) !== JSON.stringify(node.contract?.inputs) ||
+        JSON.stringify(unit.unit.outputs) !== JSON.stringify(node.contract?.outputs)) issues.push(`권한 표: 동사 단위 미해석 ${node.call}`);
+    } catch { issues.push(`권한 표: 동사 단위 미해석 ${node.call}`); }
+  }
+  return [...new Set(issues)];
+}
+
+export async function composeMissionGraph(input: MissionComposeInput, deps: Pick<GraphWizardDeps, 'callLLM'> & { deferPersistence?: boolean } = {}): Promise<{
+  selection: CompositionSelection; reason: string; persist: () => void;
+}> {
+  const fallback = input.standard;
+  let files: string[] = [];
+  try { files = readdirSync(join(input.root, 'graphs/work')).filter(name => name.endsWith('.yaml') && name !== 'recipes.yaml'); }
+  catch { /* The fixed selection already carries the missing or unreadable-template reason. */ }
+  const candidates = files.flatMap(file => {
+    const path = join(input.root, 'graphs/work', file);
+    try {
+      const yaml = readFileSync(path, 'utf8');
+      const parsed = parseGraphTemplateYaml(yaml, path);
+      return parsed.template && !parsed.errors.length && (parseYaml(yaml) as { launcher?: unknown }).launcher
+        ? [{ file: `graphs/work/${file}`, yaml, template: parsed.template }] : [];
+    } catch { return []; }
+  });
+  const standardFile = fallback.composition?.file;
+  const words = input.text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+  const score = (item: { file: string; template: GraphTemplateSpec }) => {
+    const label = `${item.file} ${item.template.graphId} ${item.template.loop?.title ?? ''} ${item.template.loop?.description ?? ''}`.toLowerCase();
+    return words.reduce((total, word) => total + (word.length > 1 && label.includes(word) ? 1 : 0), 0);
+  };
+  const standardLauncher = standardFile ? candidates.find(item => item.file === standardFile) : undefined;
+  const compatible = candidates.filter(item => (parseYaml(item.yaml) as { launcher: unknown }).launcher ===
+    (standardLauncher ? (parseYaml(standardLauncher.yaml) as { launcher: unknown }).launcher : undefined)
+    && item.template.nodes.every(node => node.kind === 'gate' || node.kind === 'subgraph' && node.call?.startsWith('verb-')));
+  const base = compatible.sort((a, b) => score(b) - score(a) || Number(b.file === standardFile) - Number(a.file === standardFile))[0];
+  const prefix = base ? `문면 선택 ${base.file} (일치 ${score(base)})` : '표준 조합 없음';
+  let generated = '';
+  let issues: string[] = [];
+  let selection = fallback;
+  if (base && base.file !== standardFile && fallback.launcher === 'graph-run' && !fallback.error) {
+    const missingUnits: string[] = [];
+    const { validateUnitCalls } = await import('../graph-runner/runner.js');
+    try { validateUnitCalls(base.template, join(input.root, base.file), [], call => missingUnits.push(call)); }
+    catch (error) { issues.push(`표준 조합 단위 해석 오류: ${error instanceof Error ? error.message : String(error)}`); }
+    if (!issues.length && !missingUnits.length) selection = {
+      composition: { file: base.file, version: base.template.version }, launcher: 'graph-run', unitsResolved: true, missingUnits: [],
+    };
+    else if (missingUnits.length) issues.push(`표준 조합 단위 미해석: ${missingUnits.join(', ')}`);
+  }
+  if (base && selection.composition && !selection.error && !issues.length &&
+    (base.file === standardFile || selection.launcher === 'graph-run')) {
+    try {
+      const proposal = await generateGraphFromPrompt({ prompt: input.text, kind: 'harness', missionBase: { id: base.template.graphId, text: base.yaml } },
+        { callLLM: deps.callLLM, graphsDir: join(input.root, 'graphs'), existingIds: () => new Set(), maxAttempts: 1 });
+      generated = proposal.yaml;
+      const launcher = (parseYaml(base.yaml) as { launcher: string }).launcher;
+      if (!(parseYaml(generated) as { launcher?: unknown }).launcher)
+        generated = generated.replace(/^(graph_id:\s*[^\n]+\n)/, `$1launcher: ${launcher}\n`);
+      issues = missionGraphIssues(generated, base.yaml, input.root,
+        join(dirname(input.ledgerPath), `${input.cardId}.generated.yaml`));
+      if (!proposal.ok) issues.push(...proposal.issues);
+      if (launcher !== 'graph-run') issues.push('권한 표: harness-say 는 생성된 graph-run 조합으로 전환할 수 없다');
+      const directory = dirname(input.ledgerPath);
+      const recipePath = join(directory, 'recipes.yaml');
+      if (existsSync(recipePath) && readFileSync(recipePath, 'utf8') !== readFileSync(join(input.root, 'graphs/work/recipes.yaml'), 'utf8'))
+        issues.push('권한 표: 원장 옆 recipes.yaml 이 표준과 다르다');
+      if (!issues.length) {
+        const target = join(dirname(input.ledgerPath), `${input.cardId}.generated.yaml`);
+        selection = { composition: { file: target, version: parseGraphTemplateYaml(generated).template!.version },
+          launcher: launcher as 'graph-run' | 'harness-say', unitsResolved: true, missingUnits: [] };
+      }
+    } catch (error) { issues.push(`생성 실패: ${error instanceof Error ? error.message : String(error)}`); }
+  } else if (!issues.length) issues.push('표준 조합을 읽을 수 없다');
+  const reason = issues.length ? `${prefix} → fallback-standard: ${issues.join('; ')}` : `${prefix} → composed: 동사 단위 검증 통과`;
+  const persist = (): void => {
+    const directory = dirname(input.ledgerPath);
+    mkdirSync(directory, { recursive: true });
+    if (generated) writeFileSync(join(directory, `${input.cardId}.generated.yaml`), generated);
+    if (selection.composition?.file === join(directory, `${input.cardId}.generated.yaml`) && !existsSync(join(directory, 'recipes.yaml')))
+      writeFileSync(join(directory, 'recipes.yaml'), readFileSync(join(input.root, 'graphs/work/recipes.yaml'), 'utf8'), { flag: 'wx' });
+    writeFileSync(join(directory, `${input.cardId}.composition.json`), JSON.stringify({ base: base?.file ?? null,
+      selected: selection.composition?.file ?? null, reason, issues, generated: generated ? `${input.cardId}.generated.yaml` : null }));
+  };
+  if (!deps.deferPersistence) persist();
+  debug.log('graph.compose', issues.length ? 'fallback-standard' : 'composed', { card: input.cardId, base: base?.file ?? null, reason });
+  return { selection, reason, persist };
+}

package/src/grok/agent-search.ts

@@ -55,6 +55,9 @@ export interface GrokAgentSearchOpts {
   signal?: AbortSignal;
   fetchImpl?: FetchLike;
   apiKey?: string;
+  /** Subscription proxy endpoint and required CLI headers. Omit for the metered xAI API. */
+  baseUrl?: string;
+  headers?: Record<string, string>;
 }
 
 export interface GrokCitation {
@@ -106,10 +109,13 @@ export async function grokAgentSearch(
 
   let res: Response;
   try {
-    res = await fetchImpl(GROK_RESPONSES_URL, {
+    const endpoint = opts.baseUrl
+      ? `${opts.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}` },
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, ...opts.headers },
       body: JSON.stringify({
         model,
         input,

package/src/grok/credential.ts

@@ -26,7 +26,7 @@
 //   「Using auth.json for API Access」 절이 유일한 문서다. ⇒ 조용히 깨질 수 있으니
 //   호출자는 실패를 fail-soft 로 접고 API 키 경로로 떨어질 수 있어야 한다.
 
-import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -98,6 +98,7 @@ export interface GrokCredential {
 interface GrokAuthScope {
   key?: unknown;
   expires_at?: unknown;
+  refresh_token?: unknown;
   user_id?: unknown;
 }
 
@@ -112,7 +113,7 @@ export function grokAuthFilePath(home: string = homedir()): string {
  *     키가 다르다(실측: 이 기계는 `https://auth.x.ai::<uuid>`). 그래서 «훑는다». */
 function readSubscriptionToken(
   path: string,
-): { token: string; expiresAt: string | null; userId: string | null } | null {
+): { token: string; expiresAt: string | null; userId: string | null; scopeName: string } | null {
   if (!existsSync(path)) return null;
   let parsed: unknown;
   try {
@@ -120,9 +121,15 @@ function readSubscriptionToken(
   } catch {
     return null;
   }
+  return selectSubscriptionToken(parsed);
+}
+
+function selectSubscriptionToken(
+  parsed: unknown,
+): { token: string; expiresAt: string | null; userId: string | null; scopeName: string } | null {
   if (!parsed || typeof parsed !== 'object') return null;
 
-  type SubscriptionToken = { token: string; expiresAt: string | null; userId: string | null; ms: number };
+  type SubscriptionToken = { token: string; expiresAt: string | null; userId: string | null; scopeName: string; ms: number };
   let best: SubscriptionToken | null = null;
   let hqMirror: SubscriptionToken | null = null;
   for (const [scopeName, scope] of Object.entries(parsed as Record<string, unknown>)) {
@@ -135,13 +142,14 @@ function readSubscriptionToken(
       token: s.key,
       expiresAt,
       userId: typeof s.user_id === 'string' ? s.user_id : null,
+      scopeName,
       ms: Number.isNaN(ms) ? Number.NEGATIVE_INFINITY : ms,
     };
     if (scopeName === 'https://auth.x.ai::hq-mirror') hqMirror = cand;
     if (best === null || cand.ms > best.ms) best = cand;
   }
-  const selected = hqMirror ?? best;
-  return selected ? { token: selected.token, expiresAt: selected.expiresAt, userId: selected.userId } : null;
+  const selected = hqMirror && (best === null || hqMirror.ms >= best.ms) ? hqMirror : best;
+  return selected ? { token: selected.token, expiresAt: selected.expiresAt, userId: selected.userId, scopeName: selected.scopeName } : null;
 }
 
 /** 호스트 발급 문이 응답에 실을 access. user id 는 반환하지 않는다. */
@@ -158,6 +166,14 @@ export function readGrokSubscriptionExpiry(home?: string): string | null {
   return readSubscriptionToken(grokAuthFilePath(home))?.expiresAt ?? null;
 }
 
+/** Read the current selected scope for a host-side launch snapshot. */
+export function readSelectedGrokScope(home?: string): { scopeName: string; key: string; expiresAt: string | null; userId: string | null; hasRefreshToken: boolean } | null {
+  const selected = readSelectedScope(grokAuthFilePath(home));
+  if (!selected) return null;
+  return { scopeName: selected.scopeName, key: selected.token, expiresAt: selected.expiresAt,
+    userId: selected.userId, hasRefreshToken: Boolean(selected.refreshToken) };
+}
+
 /** 프록시 필수 헤더. ⛔ `x-grok-client-version` 을 빼면 426 이다(실측). */
 export function grokSubscriptionHeaders(opts: {
   model?: string;
@@ -329,6 +345,11 @@ function readGrokCredential(opts: {
   return null;
 }
 
+/** Read-only credential check for synchronous provider availability. Never refreshes or calls the network. */
+export function peekGrokCredential(opts: { home?: string; model?: string } = {}): GrokCredential | null {
+  return readGrokCredential(opts);
+}
+
 export interface ResolveGrokCredentialOpts {
   env?: NodeJS.ProcessEnv;
   home?: string;
@@ -366,23 +387,58 @@ export function resolveGrokCredential(opts: ResolveGrokCredentialOpts = {}): Gro
 
 /** 갱신 유도 결과. ⛔ 「갱신됐다」와 «안 됐다»와 «못 했다»를 다른 값으로. */
 export type GrokRefreshOutcome = 'refreshed' | 'unchanged' | 'failed' | 'no-credential';
+const grokSubscriptionRefreshesInProgress = new Set<string>();
 
 /** 토큰의 만료 시각만 뽑는다(비교용). ⛔ 토큰 값은 안 낸다. */
-function readExpiresAt(path: string): string | null {
-  if (!existsSync(path)) return null;
+function readSelectedScope(path: string): { token: string; expiresAt: string | null; refreshToken: string | null; scopeName: string; userId: string | null } | null {
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!parsed || typeof parsed !== 'object') return null;
-    let latest: string | null = null;
-    for (const scope of Object.values(parsed as Record<string, unknown>)) {
-      if (!scope || typeof scope !== 'object') continue;
-      const raw = (scope as GrokAuthScope).expires_at;
-      if (typeof raw === 'string' && (latest === null || raw > latest)) latest = raw;
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown>;
+    const selected = selectSubscriptionToken(parsed);
+    if (!selected) return null;
+    const scope = parsed[selected.scopeName];
+    if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return null;
+    const value = scope as GrokAuthScope;
+    if (value.key !== selected.token) return null;
+    return {
+      token: selected.token,
+      expiresAt: selected.expiresAt,
+      refreshToken: typeof value.refresh_token === 'string' && value.refresh_token.trim() ? value.refresh_token : null,
+      scopeName: selected.scopeName,
+      userId: selected.userId,
+    };
+  } catch { return null; }
+}
+
+function acquireGrokRefreshFileLock(path: string, timeoutMs: number): (() => void) | null {
+  const lock = `${path}.refresh-lock`;
+  const deadline = Date.now() + timeoutMs;
+  mkdirSync(join(path, '..'), { recursive: true });
+  while (Date.now() <= deadline) {
+    try {
+      mkdirSync(lock, { mode: 0o700 });
+      writeFileSync(join(lock, 'owner'), `${process.pid} ${Date.now()}`, { mode: 0o600, flag: 'wx' });
+      return () => { try { rmSync(lock, { recursive: true, force: true }); } catch { /* best effort */ } };
+    } catch {
+      try {
+        const owner = readFileSync(join(lock, 'owner'), 'utf8').trim().split(/\s+/);
+        const pid = Number(owner[0]);
+        const started = Number(owner[1]);
+        let alive = false;
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); alive = true; } catch (error) { alive = (error as NodeJS.ErrnoException).code === 'EPERM'; }
+        }
+        // The holder may outlive this waiter's timeout; only a dead PID is stale.
+        if (!alive && Number.isFinite(started) && Date.now() - started > 30_000) rmSync(lock, { recursive: true, force: true });
+      } catch {
+        // A crash between mkdir and writing owner leaves no PID to inspect.
+        // Give a live creator time to finish, then recover the orphan directory.
+        try { if (Date.now() - statSync(lock).mtimeMs > 30_000) rmSync(lock, { recursive: true, force: true }); }
+        catch { /* another process may be creating or removing the lock */ }
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
     }
-    return latest;
-  } catch {
-    return null;
   }
+  return null;
 }
 
 /**
@@ -412,30 +468,51 @@ export function refreshGrokSubscriptionToken(
     timeoutMs?: number;
     /** ⛔ 테스트 심 — 실 바이너리 없이 계약을 문다. */
     execImpl?: (cmd: string, args: string[], timeoutMs: number) => void;
+    /** Require a non-empty refresh token on the selected access scope before launching the CLI. */
+    requireRefreshToken?: boolean;
+    requiredValidityMs?: number;
+    nowMs?: number;
   } = {},
 ): GrokRefreshOutcome {
   const path = grokAuthFilePath(opts.home);
-  const before = readExpiresAt(path);
-  if (before === null && !existsSync(path)) return 'no-credential';
-
+  const selected = readSelectedScope(path);
+  if (!selected) return 'no-credential';
+  if (opts.requireRefreshToken && !selected.refreshToken) return 'no-credential';
+  // A nested refresh for the same auth file observes the outer call's result later.
+  if (grokSubscriptionRefreshesInProgress.has(path)) return 'unchanged';
+  grokSubscriptionRefreshesInProgress.add(path);
+  const releaseLock = acquireGrokRefreshFileLock(path, opts.timeoutMs ?? 20_000);
+  if (!releaseLock) { grokSubscriptionRefreshesInProgress.delete(path); return 'failed'; }
   try {
+    const current = readSelectedScope(path);
+    if (!current || current.scopeName !== selected.scopeName) return 'no-credential';
+    if (opts.requireRefreshToken && !current.refreshToken) return 'no-credential';
+    // Only the Pod preflight supplies a validity target. An explicit refresh call still invokes the CLI.
+    const expiresMs = current.expiresAt ? Date.parse(current.expiresAt) : NaN;
+    if (opts.requiredValidityMs !== undefined && Number.isFinite(expiresMs)
+      && expiresMs - (opts.nowMs ?? Date.now()) >= opts.requiredValidityMs) return 'unchanged';
     const timeoutMs = opts.timeoutMs ?? 20_000;
-    if (opts.execImpl) {
-      opts.execImpl(opts.grokPath ?? 'grok', ['models'], timeoutMs);
-    } else {
-      const { execFileSync } = require('node:child_process') as typeof import('node:child_process');
-      execFileSync(opts.grokPath ?? 'grok', ['models'], {
-        timeout: timeoutMs,
-        stdio: ['ignore', 'ignore', 'ignore'],
-      });
-    }
-  } catch {
-    return 'failed';
+    try {
+      if (opts.execImpl) {
+        opts.execImpl(opts.grokPath ?? 'grok', ['models'], timeoutMs);
+      } else {
+        const { execFileSync } = require('node:child_process') as typeof import('node:child_process');
+        execFileSync(opts.grokPath ?? 'grok', ['models'], {
+          timeout: timeoutMs,
+          stdio: ['ignore', 'ignore', 'ignore'],
+        });
+      }
+    } catch { return 'failed'; }
+    const after = readSelectedScope(path);
+    if (!after) return 'no-credential';
+    const afterMs = after?.expiresAt ? Date.parse(after.expiresAt) : NaN;
+    return after?.scopeName === current.scopeName && Number.isFinite(afterMs)
+      && (!Number.isFinite(expiresMs) || afterMs > expiresMs)
+      ? 'refreshed' : 'unchanged';
+  } finally {
+    releaseLock();
+    grokSubscriptionRefreshesInProgress.delete(path);
   }
-
-  const after = readExpiresAt(path);
-  // ⛔ 「돌았다」가 아니라 「만료가 «앞으로» 갔다」를 본다.
-  return after !== null && after !== before ? 'refreshed' : 'unchanged';
 }
 
 // ── ⭐ 「접힌」 자격 해석 — 호출자가 «기억할 것»을 0 으로 ────────────────────────
@@ -492,7 +569,6 @@ export function isGrokSubscriptionExpiring(
 
 /** 구독 만료 상태 — 칸 CRED-EXPIRY-REFRESH 기준 창. 이 안에 만료가 오면 갱신 후보다. */
 export const GROK_EXPIRY_SOON_WINDOW_MS = 2 * 60 * 60 * 1000;
-
 /** 만료 상태 셋 — ⛔ boolean 으로 접으면 「모름」과 «여유»가 «같은 값»이 된다. */
 export type GrokSubscriptionExpiryState = 'healthy' | 'expiring' | 'unknown';
 

package/src/grounding/ref-index.ts

@@ -50,6 +50,8 @@ export interface ReferenceCard {
   kind: GroundingSource['kind'];
   name: string;
   oneLine: string;
+  /** Relative path that supplied oneLine, when a README was readable. */
+  oneLineFile?: string;
   directories: string[];
   receivedAt?: string;
   /** L1 */
@@ -57,6 +59,13 @@ export interface ReferenceCard {
   commands: string[];
   /** A file-count or byte limit cut the read short — the lists may be incomplete. */
   truncated: boolean;
+  /** Stable identity of this card inside the grounding orchestration log. */
+  orchestrationId: string;
+}
+
+/** Stable identity of this card inside the grounding orchestration log. */
+export function orchestrationId(kind: string, id: string): string {
+  return `grounding:${kind}:${id}`;
 }
 
 export function buildReferenceCard(
@@ -132,11 +141,13 @@ export function buildReferenceCard(
     kind: source.kind,
     name: packageName ?? basename(root),
     oneLine,
+    ...(oneLine && readme ? { oneLineFile: readme.name } : {}),
     directories,
     ...(receivedAt ? { receivedAt } : {}),
     titles,
     commands,
     truncated,
+    orchestrationId: orchestrationId(source.kind, source.id),
   };
 }
 

package/src/grounding/ref-vector.ts

@@ -0,0 +1,61 @@
+import type { Database } from 'bun:sqlite';
+import { chunkReport, hybridQueryKnowledge, ingestText, type EmbedFn, type HybridMatch } from '../domains/knowledge.js';
+import type { ReferenceCard } from './ref-index.js';
+
+export interface ReferenceIngestOptions {
+  embed: EmbedFn;
+  maxChunks?: number;
+}
+
+export interface ReferenceQueryOptions {
+  embed: EmbedFn;
+  k?: number;
+}
+
+/** Keep the source ID and a real relative file path together in each returned citation. */
+function sourceRef(id: string, file: string): string | null {
+  if (!id || !file || file.startsWith('/') || /^[a-zA-Z]:/.test(file) || file.split(/[\\/]/).some((part) => part === '..' || part === '.')) return null;
+  return `${id}#${file}`;
+}
+
+/** Index only card text whose original file is known; an invented README path must never become a citation. */
+export async function ingestReferenceCard(
+  db: Database,
+  card: ReferenceCard,
+  opts: ReferenceIngestOptions,
+): Promise<{ ingested: number; truncated: boolean }> {
+  const maxChunks = opts.maxChunks ?? 200;
+  if (!Number.isSafeInteger(maxChunks) || maxChunks < 0) throw new Error('reference maxChunks must be a nonnegative integer');
+  const entries: Array<{ file: string; text: string }> = [];
+  if (card.oneLine && card.oneLineFile) entries.push({ file: card.oneLineFile, text: card.oneLine });
+  for (const title of card.titles) entries.push({ file: title.file, text: title.title });
+  for (const command of card.commands) entries.push({ file: 'package.json', text: command });
+  const chunks = entries.flatMap(({ file, text }) => {
+    const ref = sourceRef(card.id, file);
+    return ref ? chunkReport(text).map((chunk) => ({ ref, text: chunk })) : [];
+  });
+  let ingested = 0;
+  const ts = card.receivedAt ?? new Date(0).toISOString();
+  for (const [index, chunk] of chunks.slice(0, maxChunks).entries()) {
+    if (await ingestText(db, {
+      id: `reference:${card.id}:${index}`,
+      ts,
+      kind: 'reference',
+      domain: 'elanous',
+      text: chunk.text,
+      source_ref: chunk.ref,
+    }, opts.embed)) ingested++;
+  }
+  return { ingested, truncated: card.truncated || chunks.length > maxChunks };
+}
+
+/** Reuse the knowledge hybrid ranker, but never return a result without a source link. */
+export async function queryReferences(
+  db: Database,
+  query: string,
+  opts: ReferenceQueryOptions,
+): Promise<HybridMatch[]> {
+  const k = Math.min(Math.max(opts.k ?? 5, 1), 20);
+  const matches = await hybridQueryKnowledge(db, query, { kind: 'reference', domain: 'elanous', k: 20, embed: opts.embed });
+  return matches.filter((match) => !!match.source_ref).slice(0, k);
+}

package/src/grounding/sources-cli.ts

@@ -118,7 +118,7 @@ export function registerGroundingSourcesCli(program: Command): void {
     .command('status [id]')
     .description('local-repo 신선도(로컬 참조만 · fetch/pull 없음)')
     .option('--json', 'JSON 출력')
-    .action((id: string | undefined, opts: { json?: boolean }) => {
+    .action(async (id: string | undefined, opts: { json?: boolean }) => {
       const listed = listGroundingSources(load());
       const targets = id ? listed.filter((source) => source.id === id) : listed;
       if (id && targets.length === 0) {
@@ -126,7 +126,7 @@ export function registerGroundingSourcesCli(program: Command): void {
         process.exitCode = 1;
         return;
       }
-      const rows = targets.map((source) => sourceStatus(source));
+      const rows = await Promise.all(targets.map((source) => sourceStatus(source)));
       if (opts.json) printJson(id ? rows[0] : rows);
       else for (const row of rows) {
         console.log(`${row.id} dirty=${String(row.dirty ?? false)} behind=${String(row.behind ?? 'unknown')}${row.branch ? ` branch=${row.branch}` : ''}`);

package/src/grounding/sources.ts

@@ -186,7 +186,21 @@ export function discoverReferenceSources(home: string): GroundingSource[] {
   return [...repos, ...docs];
 }
 
-export function sourceStatus(source: GroundingSource): GroundingSourceStatus {
+export async function sourceStatus(source: GroundingSource): Promise<GroundingSourceStatus> {
+  if ((source.kind === 'local-repo' || source.kind === 'local-docs') && source.path) {
+    // Wiring: the reference card is built from the existing status path (local git refs only).
+    try {
+      const { buildReferenceCard, nodeRefIndexFs } = await import('./ref-index.js');
+      const card = buildReferenceCard(source, nodeRefIndexFs);
+      debug.log('grounding.sources', 'card', {
+        id: source.id,
+        name: card.name,
+        orchestrationId: card.orchestrationId,
+      });
+    } catch (error) {
+      debug.log('grounding.sources', 'card-skip', { id: source.id, error: String(error) });
+    }
+  }
   if (source.kind !== 'local-repo' || !source.path) {
     const status: GroundingSourceStatus = { id: source.id, kind: source.kind, measured: false };
     debug.log('grounding.sources', 'status', { id: source.id, behind: 'unknown', dirty: false });