elanous 0.2.36 → 0.2.38

package/src/graph-runner/runner.ts

@@ -17,6 +17,7 @@ import { recordFailureEvent } from '../self-implement/heal-intake.js';
 import { growthApprovalRef, proposeGrowth, type GraphGrowth, type GrowthProposer, type GrowthRecipeEffect, type GrowthDecisionDeps, type GrowthCommand } from './graph-grow.js';
 import { DecisionLedger, type DecisionEntry } from '../decisions/decision-ledger.js';
 import { createLLMGrowthProposer } from './graph-grow-llm.js';
+import type { ResearchEdgeDecisionRegistry } from '../research/edge-decision.js';
 import { graphVersionHash, parseGraphTemplateYaml, type GraphEdgeSpec, type GraphNodeSpec, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
 import { createGraphUnitResolver, resolveGraphUnit, UnitNotFoundError, type ResolvedGraphUnit } from '../self-implement/graph-unit-resolver.js';
 import { flattenGraphUnits } from '../self-implement/graph-unit-flatten.js';
@@ -34,6 +35,7 @@ const DEFAULT_BASH_TIMEOUT_MS = 5 * 60 * 1_000;
 // Independent of graph YAML and recipe snapshots: an already-wrong saved binding must fail closed.
 const RELEASE_NODE_COMMANDS: Readonly<Record<string, { recipe: string; command?: string }>> = {
   'version-release': { recipe: 'cmd:version-release', command: 'bun scripts/release-loop/version-node.ts release --json' },
+  'traffic-cut-start': { recipe: 'cmd:traffic-cut-start', command: 'bun scripts/release-loop/traffic-node.ts traffic-cut-start' },
   cutoff: { recipe: 'cmd:cutoff', command: 'bun scripts/release-loop/node-verdict.ts cutoff' },
   'checklist-gate': { recipe: 'cmd:checklist-gate', command: 'bun scripts/release-loop/checklist-gate-node.ts' },
   prefetch: { recipe: 'cmd:docs', command: 'bun scripts/release-loop/docs-node.ts --json' },
@@ -55,9 +57,11 @@ const RELEASE_NODE_COMMANDS: Readonly<Record<string, { recipe: string; command?:
   'approve-publish': { recipe: 'approval:publish' },
   publish: { recipe: 'cmd:publish-command', command: 'bun scripts/release-loop/publish-node.ts' },
   'npm-publish': { recipe: 'cmd:npm-publish', command: 'bun scripts/release-loop/npm-publish-node.ts' },
+  'traffic-npm-published': { recipe: 'cmd:traffic-npm-published', command: 'bun scripts/release-loop/traffic-node.ts traffic-npm-published' },
   'docs-land': { recipe: 'cmd:docs-land', command: 'bun scripts/release-loop/docs-land-node.ts' },
   verify: { recipe: 'cmd:verify', command: 'bun scripts/release-loop/verify-node.ts' },
   'traffic-verify-complete': { recipe: 'cmd:traffic-verify-complete', command: 'bun scripts/release-loop/traffic-node.ts traffic-verify-complete' },
+  'traffic-failed-restore': { recipe: 'cmd:traffic-failed-restore', command: 'bun scripts/release-loop/traffic-node.ts traffic-failed-restore' },
   'vault-note': { recipe: 'cmd:vault-note', command: 'bun scripts/release-loop/vault-note-node.ts' },
   'release-story': { recipe: 'cmd:release-story', command: 'bun scripts/release-story/draft.ts --graph' },
   'ops-upgrade': { recipe: 'cmd:ops-upgrade', command: 'bun scripts/release-loop/ops-upgrade-node.ts' },
@@ -144,7 +148,7 @@ export interface GraphRunState {
   reason?: string;
   path: string[];
   /** startedAt/endedAt (ISO) and seconds are written when the node runs; ledgers before GRAPH-NODE-TIMES (0.2.19) have none. */
-  nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; decidedBy?: string; decidedAt?: string;
+  nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; reason?: string; decidedBy?: string; decidedAt?: string;
     startedAt?: string; endedAt?: string; seconds?: number;
     waiver?: { reason: string; at: string; /** RELEASE-WAIVE-UNMEASURED — why the waived gate had no verdict. */ unmeasured?: string; original: { exit: number | null; output?: unknown; error?: string } } }>;
   /** The node now running and when it started; cleared when its record is written. */
@@ -172,6 +176,11 @@ export interface GraphRunState {
   statePath: string;
 }
 
+function failedCommandStderrTail(exitCode: number, stderr: string): string | undefined {
+  if (exitCode === 0 || !stderr.trim()) return undefined;
+  return stderr.replace(/(?:\r?\n)+$/, '').split(/\r?\n/).slice(-40).join('\n') || undefined;
+}
+
 export interface GraphClassifyInput {
   arguments: string;
   classify: ClassifyNode['classify'];
@@ -243,6 +252,8 @@ export interface GraphRunOptions {
   pinChildUniverse?: boolean;
   /** Release resume: command checkout and cut tip, checked before every Bash dispatch. */
   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[] } };
 }
 
@@ -834,7 +845,16 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         const next = nextNode(graph.edges, prior.nodeId, prior.ok ? 'ok' : 'fail', typeof reported === 'string' ? reported : undefined);
         if (next !== recorded.nodeId) throw new Error('saved run path does not follow graph edges');
       } else if (recorded.nodeId !== unitEntryNode) throw new Error('saved run path does not start at entry node');
-      if (i < from && !recorded.ok) throw new Error('cannot preserve a failed predecessor when resuming');
+      if (i < from && !recorded.ok) {
+        // A warning-only node explicitly sends every outcome to the same next
+        // node. Its truthful failed record is safe to preserve when retrying a
+        // later release step; a branching failure is still a hard stop.
+        const edge = graph.edges.find((candidate) => candidate.from === recorded.nodeId);
+        const next = state.path[i + 1];
+        if (edge?.on !== 'outcome' || !next || !(['ok', 'fail', 'error'] as const).every((outcome) => edge.map?.[outcome] === next)) {
+          throw new Error('cannot preserve a failed predecessor when resuming');
+        }
+      }
       const approved = resolveNodeRecipe(spec, recipes, catalogRoles).approval;
       if (approved && i >= from) throw new Error('cannot restart across an approval decision');
       if (approved && i < from) {
@@ -1071,6 +1091,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     let ok = approval && !state.dryRun ? state.pending?.decision === 'approved' : true;
     let exit: number | null = null;
     let error: string | undefined;
+    let commandFailureReason: string | undefined;
     let output: unknown;
     const waiving = options.releaseWaiver?.nodeId === current && waivedRecord !== undefined;
     if (command && !waiving && (!approval || state.dryRun || ok) && (!state.dryRun || command.dry_run_command) && !resumingCompleted) {
@@ -1105,7 +1126,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         try {
           const result = await execute(body, commandRoot ? { ...opts, cwd: commandRoot } : opts);
           code = result.exitCode;
-          return { ...result, stdout: redactCredentials(result.stdout), stderr: redactCredentials(result.stderr) };
+          const stderr = redactCredentials(result.stderr);
+          commandFailureReason = failedCommandStderrTail(result.exitCode, stderr);
+          return { ...result, stdout: redactCredentials(result.stdout), stderr };
         } finally {
           if (state.activeNode?.nodeId === current) {
             delete state.activeNode;
@@ -1296,13 +1319,14 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       exit = completed.exit;
       output = completed.output;
       error = completed.error;
+      commandFailureReason = completed.reason;
     } else {
       // 승인 노드도 결과를 «값»으로 남긴다 — 뒤 노드가 문맥(outputs)에서 승인 여부를 확인할 수 있게(발행 노드가 승인 없이 돌지 않도록).
       if (approval && !state.dryRun && !command) {
         output = JSON.stringify({ outcome: ok ? 'approved' : 'rejected', graphId, runId, nodeId: current,
           ...(state.pending?.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending?.decidedAt ?? null });
       }
-      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 && ((!!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 } : {}), ...(commandFailureReason ? { 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 } : {}),
         startedAt: nodeStartedAt, endedAt: nodeEndedAt, seconds });
@@ -1318,10 +1342,13 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     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 namedOutcome: string | undefined = typeof reported === 'string' ? reported : undefined;
     if (!options.quiet) console.error(`[graph] ${current} ${ok ? 'ok' : 'fail'} (${seconds.toFixed(2)}s)`);
-    debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit });
+    debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit,
+      ...(commandFailureReason ? { reason: commandFailureReason } : {}) });
     publishInsideEvent({ kind: 'node', graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds });
     publishInsideEvent({ kind: 'verdict', graphId, runId, nodeId: current, verdict: ok ? 'ok' : 'fail', ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }) });
-    log('node-end', { graphId, runId, nodeId: current, ok, exit, ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }), dryRun: state.dryRun });
+    log('node-end', { graphId, runId, nodeId: current, ok, exit,
+      ...(commandFailureReason ? { reason: commandFailureReason } : {}),
+      ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }), dryRun: state.dryRun });
     if (!resumingCompleted) {
       // Recipe commands expose stdout/exit but no provider usage; never infer zero from success.
       observeModelInputTokens({ scope: 'harness-node', nodeKind: node.kind, runId, nodeId: current });
@@ -1351,7 +1378,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
             if (!resolved.command && !resolved.approval && candidate.recipe !== 'none') return 'unknown';
             return { effect: resolved.approval ? 'unknown' : options.deps?.classifyGrowthRecipe?.(candidate, { command: resolved.command?.command }) ?? 'unknown',
               command: resolved.command, approval: resolved.approval?.approval };
-          }, { ...options.deps?.growthDecision, root });
+          }, { ...options.deps?.growthDecision, root }, options.researchEdgeDecisionRegistry);
       if (result.ok) {
         graph = result.graph;
         state.growth ??= [];

package/src/graph-wizard/generate.ts

@@ -93,14 +93,36 @@ export function listKnownGraphUnits(dir = defaultGraphsDir()): KnownGraphUnit[]
   }).sort((a, b) => a.call.localeCompare(b.call));
 }
 
+/** 호출 경계로 올리는 조작 growth 요약 — 어느 from 노드에서 무엇을 끼우려 했나. */
+export interface GraphVariantGrowthTrace {
+  readonly from: string;
+  readonly outcome: string;
+  readonly nodeId: string;
+  readonly returnTo?: string;
+}
+
+/**
+ * 설계자 한 턴의 결말 — mode·reason 은 호출 경계가 관측으로 기록하는 필드다(composed 는 'composed',
+ * fallback-standard 는 그 사유 문자열 그대로). growth 는 설계자가 조작한 from 노드를 그대로 올린다.
+ */
 export type GraphVariantDesignResult =
-  | { readonly status: 'composed'; readonly plan: GraphVariantPlan; readonly variant: Extract<GraphVariantResult, { ok: true }> }
-  | { readonly status: 'fallback-standard'; readonly template: GraphTemplateSpec; readonly reason: string };
+  | { readonly mode: 'variant'; readonly status: 'composed'; readonly reason: 'composed'; readonly plan: GraphVariantPlan; readonly variant: Extract<GraphVariantResult, { ok: true }>; readonly growth?: GraphVariantGrowthTrace }
+  | { readonly mode: 'variant'; readonly status: 'fallback-standard'; readonly template: GraphTemplateSpec; readonly reason: string; readonly growth?: GraphVariantGrowthTrace };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+/** 설계자 출력에서 조작 growth 의 좌표만 읽는다 — 모양이 틀려도 «어느 from 이었나»는 남긴다. */
+function growthTraceOf(record: Record<string, unknown> | null): GraphVariantGrowthTrace | undefined {
+  const growth = record?.growth;
+  if (!isRecord(growth) || typeof growth.from !== 'string' || typeof growth.outcome !== 'string') return undefined;
+  const node = isRecord(growth.node) ? growth.node : undefined;
+  if (typeof node?.nodeId !== 'string') return undefined;
+  return { from: growth.from, outcome: growth.outcome, nodeId: node.nodeId,
+    ...(typeof growth.returnTo === 'string' ? { returnTo: growth.returnTo } : {}) };
+}
+
 /** One L2 designer proposal. The model returns only a plan; the existing variant authority decides whether it may run. */
 export async function designGraphVariantPlan(input: {
   readonly goal: string;
@@ -127,9 +149,10 @@ export async function designGraphVariantPlan(input: {
   catch (error) {
     const reason = `designer-output: ${error instanceof Error ? error.message : String(error)}`;
     debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
-    return { status: 'fallback-standard', template: input.template, reason };
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason };
   }
   const record = isRecord(raw) ? raw : null;
+  const growthTrace = growthTraceOf(record);
   const allowed = new Set(['maxVisits', 'routes', 'growth']);
   const maxVisits = record?.maxVisits;
   const routes = record?.routes;
@@ -158,17 +181,17 @@ export async function designGraphVariantPlan(input: {
   if (!valid) {
     const reason = 'designer-output: invalid GraphVariantPlan or unknown unit';
     debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
-    return { status: 'fallback-standard', template: input.template, reason };
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason, ...(growthTrace ? { growth: growthTrace } : {}) };
   }
   const plan = record as GraphVariantPlan;
   const variant = createGraphVariant({ template: input.template, goal: input.goal, plan });
   if (!variant.ok) {
     const reason = `variant-rejected: ${JSON.stringify(variant.rejections)}`;
     debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
-    return { status: 'fallback-standard', template: input.template, reason };
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason, ...(growthTrace ? { growth: growthTrace } : {}) };
   }
   debug.log('graph.compose', 'composed', { goal: input.goal, overlayId: variant.overlay.overlayId, patches: variant.patches.length });
-  return { status: 'composed', plan, variant };
+  return { mode: 'variant', status: 'composed', reason: 'composed', plan, variant, ...(growthTrace ? { growth: growthTrace } : {}) };
 }
 
 /** Inventory used by the editor's pack picker and the wizard's validation. */

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;
@@ -366,23 +382,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 +463,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 +564,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';