elanous 0.2.6 → 0.2.7

package/src/nexus/api/trace-run-scan.ts

@@ -0,0 +1,37 @@
+import { statSync } from 'node:fs';
+import type { LogInstanceView } from '../../mss/logging/instance-registry.js';
+import type { LogStore } from '../../mss/logging/log-store.js';
+
+/** Bounded, read-only fallback when a run's ledger is not on this host. */
+export function scanStoresForRun(
+  runId: string,
+  views: readonly LogInstanceView[],
+  open: (view: LogInstanceView) => Pick<LogStore, 'queryTraceRun' | 'close'> | null,
+  opts: { sinceMs?: number; untilMs?: number; maxStores?: number; deadlineMs?: number; now?: () => number } = {},
+): { universe?: string; checked: number; truncated: boolean; unresolved?: boolean } {
+  const now = opts.now ?? Date.now;
+  const deadline = now() + (opts.deadlineMs ?? 3000);
+  const maxStores = opts.maxStores ?? 200;
+  const mtime = (view: LogInstanceView): number => {
+    try { return statSync(view.dbPath).mtimeMs; } catch { return -Infinity; }
+  };
+  const candidates = views.map((view) => ({ view, at: view.dbExists ? mtime(view) : -Infinity }))
+    .sort((a, b) => (b.at === a.at ? a.view.name.localeCompare(b.view.name) : b.at - a.at));
+  let checked = 0;
+  let unresolved = false;
+  for (const { view } of candidates) {
+    if (checked >= maxStores || now() >= deadline) return { checked, truncated: true };
+    checked++;
+    let store: ReturnType<typeof open> = null;
+    try {
+      if (!view.dbExists) continue;
+      store = open(view);
+      if (!store) { unresolved = true; continue; }
+      if (store.queryTraceRun(runId, { sinceMs: opts.sinceMs, untilMs: opts.untilMs, limit: 1 }).length) {
+        return { universe: view.name, checked, truncated: false };
+      }
+    } catch { unresolved = true; }
+    finally { try { store?.close(); } catch { /* read-only handle cleanup is best effort */ } }
+  }
+  return { checked, truncated: false, ...(unresolved ? { unresolved } : {}) };
+}

package/src/nexus/api/trace.ts

@@ -8,6 +8,7 @@ import { activeStoreNames, parseSinceParam, type LogFabricDeps, registeredLogSto
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './json-response.js';
 import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
+import { scanStoresForRun } from './trace-run-scan.js';
 
 export type TraceLevel = 'L0' | 'L1' | 'L2' | 'L3';
 export interface TraceEvent {
@@ -346,7 +347,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     }
     if (!opened) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: failures }, 503);
     const runId = url.searchParams.get('runId');
-    let resolution: { universe?: string; checked: number } | undefined;
+    let resolution: { universe?: string; checked: number; truncated?: boolean; unresolved?: boolean } | undefined;
+    let resolvedFrom: 'ledger' | 'log-scan' | undefined;
     if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url)) && !requestedUniverse) {
       // A store with no log db at all («has no log store yet» — e.g. the daemon's own tree-derived universe) cannot
       // hold the run, so it must not block the ledger lookup. A store that exists but failed to open/read still does:
@@ -356,6 +358,20 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       try { resolution = findRunUniverse(runId, names, deps); }
       catch (error) { return jsonResponse({ ok: false, error: 'run-universe-unavailable', reason: error instanceof Error ? error.message : String(error) }, 503); }
       try { debug.log('nexus.trace', 'run-universe-resolved', { runId, universe: resolution.universe ?? 'not-found', checked: resolution.checked }); } catch { /* observation must not block reads */ }
+      if (resolution.universe) resolvedFrom = 'ledger';
+      else {
+        let views: LogInstanceView[];
+        try { views = (deps.instances ?? readLogInstances)(); }
+        catch (error) { return jsonResponse({ ok: false, error: 'run-universe-unavailable', reason: error instanceof Error ? error.message : String(error) }, 503); }
+        resolution = scanStoresForRun(runId, views, (view) => {
+          const store = (deps.openRemoteStore ?? ((v: LogInstanceView) => LogStore.openReadOnly(v.dbPath)))(view);
+          if (!store) return null;
+          return { queryTraceRun: (id, query) => store.queryTraceRun(id, query),
+            close: () => (deps.closeRemoteStore ?? ((s: LogStore) => s.close()))(store) };
+        }, { sinceMs: parsed.from, untilMs: parsed.to });
+        if (resolution.universe) resolvedFrom = 'log-scan';
+        try { debug.log('nexus.trace', 'run-universe-scanned', { runId, universe: resolution.universe ?? (resolution.truncated || resolution.unresolved ? 'unresolved' : 'not-found'), checked: resolution.checked, truncated: resolution.truncated }); } catch { /* observation must not block reads */ }
+      }
       if (resolution.universe && !names.includes(resolution.universe)) {
         const name = resolution.universe;
         names.push(name);
@@ -373,9 +389,9 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       }
     }
     const filtered = rows.filter((row) => matches(row, url)).sort(sortRows);
-    const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0);
+    const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0 || resolution?.truncated === true);
     try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'rows', runs: trace.nodes.filter((node) => node.level === 'L1' && node.count > 0).length }); } catch { /* query logging must not block reads */ }
-    return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom: 'ledger' as const, runUniverse: resolution.universe } : { runUniverse: 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);
+    return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom, runUniverse: resolution.universe, ...(resolvedFrom === 'log-scan' ? { checked: resolution.checked } : {}) } : { runUniverse: resolution.truncated || resolution.unresolved ? 'unresolved' as const : 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);
   } finally { closeStores(stores, deps); }
 }
 

package/src/nexus/index.ts

@@ -2626,9 +2626,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
               getBot: () => getBotRef.current,
               allowedUsers: [...cfg.discord.allowedUsers],
             });
+            const chatChannels = cfg.discord.chatChannels ?? [];
+            debug.log('nexus.discord', 'chat-channels', { count: chatChannels.length });
             const handle = createNexusDiscordTriggerBot({
               token: discordToken,
               allowedUsers: [...cfg.discord.allowedUsers],
+              ...(chatChannels.length ? { guildTextChannels: chatChannels } : {}),
               dispatch: (event) => workflowDaemon!.dispatchDiscord(event),
               onMessage: composedOnMessage,
               onInteraction: async (raw) => {

package/src/nexus/setup-status.ts

@@ -13,6 +13,7 @@ import type { UserConfig as NexusUserConfig } from './config/types.js';
 import { resolveLaunchdEnvironment } from './install/launchd.js';
 import { resolveSystemdEnvironment } from './install/systemd.js';
 import { resolvePwaStaticDir } from './static-dir-resolve.js';
+import { SKILLS_STEP_COMMAND, unattendedSetupHint } from '../onboarding/entry-hints.js';
 
 export type SetupItemId = 'llm' | 'pwa-build' | 'channel-bot' | 'skill-dirs' | 'os-install';
 
@@ -97,8 +98,6 @@ export interface SetupCheckOpts {
   decideProviderForConfig?: typeof decideProviderForConfig;
 }
 
-const UNATTENDED_SETUP_HINT = 'unattended: `elanous setup --non-interactive --config <ans.json>`';
-
 function hasText(value: unknown): boolean {
   return typeof value === 'string' && value.trim().length > 0;
 }
@@ -146,7 +145,7 @@ function checkLlm(
     id: 'llm',
     label: 'LLM provider',
     passed,
-    hint: `run \`elanous setup llm\` or interactive \`elanous nexus\`; ${UNATTENDED_SETUP_HINT}`,
+    hint: `run \`elanous onboarding llm\` or interactive \`elanous nexus\`; ${unattendedSetupHint()}`,
     ...(detailProvider && detailProvider !== 'none' ? {
       detail: `provider=${detailProvider}${credential ? ` · credential=${credential}` : ''}`,
     } : {}),
@@ -173,7 +172,7 @@ function checkChannelBot(cfg: NexusUserConfig): SetupItem {
     id: 'channel-bot',
     label: 'Channel bot',
     passed: hasText(telegram) || hasText(discord),
-    hint: `run \`elanous nexus channel-bot setup telegram|discord\`; ${UNATTENDED_SETUP_HINT}`,
+    hint: `run \`elanous nexus channel-bot setup telegram|discord\`; ${unattendedSetupHint()}`,
   };
 }
 
@@ -187,7 +186,7 @@ function checkSkillDirs(cfg: MainUserConfig, exists: (path: string) => boolean):
     label: 'Skill dirs',
     passed: existingDirs.length > 0,
     hint: missingDirs.length > 0
-      ? `create the missing skill directories or choose an already-existing skill directory; ${UNATTENDED_SETUP_HINT}`
+      ? `create the missing skill directories or choose an already-existing skill directory; run \`${SKILLS_STEP_COMMAND}\`; ${unattendedSetupHint()}`
       : '',
     ...(dirs.length > 0 ? {
       detail: missingDirs.length > 0 ? `${detail} · missing: ${missingDirs.join(', ')}` : detail,

package/src/notify/llm-budget-alert.ts

@@ -42,6 +42,8 @@ export interface LlmBudgetAlert {
 }
 
 const EXPIRY_WARN_DAYS = 7;
+/** 공개 알림에 표시할 수 있는 폴백 제공자명. 현재 폴백 체인의 외부 제공자는 grok 뿐이다. */
+const PUBLIC_FALLBACK_PROVIDERS = new Set(['grok']);
 /** 이 시각(서울) 뒤에야 «오늘 페이스가 느리다»를 말한다 — 아침에 0 인 건 정상이다. */
 const PACE_CHECK_HOUR = 18;
 
@@ -87,22 +89,26 @@ export function buildLlmBudgetAlert(now: LlmBudgetSnapshot, prevKey?: string): L
       `구독 계정 ${accounts}개 한도 · 크레딧·대체 모델도 못 씁니다.`,
       '할 일: 크레딧 사용을 허락하거나 대체 모델 키를 확인해 주세요.',
     ];
-  } else if (now.selected.reason === 'fallback' && now.fallback) {
-    const soonest = now.accounts.map((a) => a.resetInHours).filter((h): h is number => typeof h === 'number').sort((a, b) => a - b)[0];
-    key = `fallback:${now.fallback.provider}`;
+  } else if (now.selected.reason === 'fallback') {
+    const soonest = now.accounts.map((a) => a.resetInHours)
+      .filter((h): h is number => typeof h === 'number' && Number.isFinite(h) && h > 0)
+      .sort((a, b) => a - b)[0];
+    const candidate = now.fallback?.provider?.trim();
+    const provider = candidate && PUBLIC_FALLBACK_PROVIDERS.has(candidate) ? candidate : undefined;
+    key = `fallback:${provider || 'unknown'}`;
     lines = [
-      `⚠️ codex 를 못 써서 ${now.fallback.provider} 로 일하고 있습니다${typeof now.fallback.remainingPct === 'number' ? `(남은 ${Math.round(now.fallback.remainingPct)}%)` : ''}.`,
+      `⚠️ codex 를 못 써서 ${provider ? `${provider} 로` : '대체 모델로'} 일하고 있습니다${typeof now.fallback?.remainingPct === 'number' ? `(남은 ${Math.round(now.fallback.remainingPct)}%)` : ''}.`,
       soonest !== undefined ? `codex 는 ${Math.ceil(soonest)}시간 뒤 돌아옵니다.` : 'codex 가 언제 돌아오는지 아직 모릅니다.',
       '할 일: 없음 — 참고만 하세요.',
     ];
-  } else if (expiryDays !== undefined && expiryDays <= EXPIRY_WARN_DAYS && now.credits.total > 0) {
-    key = `expiry:${Math.max(0, expiryDays)}`;
+  } else if (expiryDays !== undefined && expiryDays >= 0 && expiryDays <= EXPIRY_WARN_DAYS && now.credits.total > 0) {
+    key = `expiry:${expiryDays}`;
     lines = [
-      `💳 크레딧 ${n(now.credits.total)} 이 ${expiryDays <= 0 ? '오늘' : `${expiryDays}일 뒤`} 사라집니다.`,
+      `💳 크레딧 ${n(now.credits.total)} 이 ${expiryDays === 0 ? '오늘' : `${expiryDays}일 뒤`} 사라집니다.`,
       creditsLine(now),
-      '할 일: 무거운 작업을 지금 맡기면 크레딧으로 돕니다.',
+      '할 일: 만료 전에 크레딧 사용을 확인해 주세요.',
     ];
-  } else if (now.credits.useFirst && now.credits.total > 0 && hour >= PACE_CHECK_HOUR && now.credits.usedToday < now.credits.paceTarget * 0.5) {
+  } else if (now.credits.useFirst && now.credits.total > 0 && (expiryDays === undefined || expiryDays >= 0) && hour >= PACE_CHECK_HOUR && now.credits.usedToday < now.credits.paceTarget * 0.5) {
     // 하루 한 번만 — 날짜를 열쇠에 넣는다.
     key = `pace-behind:${date}`;
     lines = [
@@ -115,5 +121,5 @@ export function buildLlmBudgetAlert(now: LlmBudgetSnapshot, prevKey?: string): L
   }
 
   const send = key !== 'ok' && key !== prevKey;
-  return { send, key, text: lines.join('\n') };
+  return { send, key, text: send ? lines.join('\n') : '' };
 }

package/src/oauth/codex-account-rotation.ts

@@ -47,6 +47,8 @@ type RotationReason =
   | 'no-candidate'
   /** 찼고 구독 잔량이 남은 계정도 없지만 대표 가 크레딧 사용을 허가했다 — 지금 계정에 머물러 선불 크레딧으로 계속(grok 폴백 안 함). */
   | 'credits-allowed'
+  /** 오늘 크레딧 몫을 먼저 쓰기 위해 찬 계정으로 이동하거나 머문다. */
+  | 'credit-pace'
   /** 넘겼다. */
   | 'rotated';
 
@@ -101,6 +103,7 @@ interface RotationInput {
   /** 지금 계정의 크레딧 잔액·보유(모르면 없다). */
   readonly currentCreditBalance?: number;
   readonly currentHasCredits?: boolean;
+  readonly creditPace?: { active: boolean };
 }
 
 /**
@@ -182,6 +185,23 @@ export function decideCodexRotation(input: RotationInput): RotationDecision {
   });
   if (input.explicit) return { reason: 'explicit', candidateCount, accountThresholds };
   if (!input.enabled) return { reason: 'disabled', candidateCount, accountThresholds, ...(input.disabledProvenance ? { disabledProvenance: input.disabledProvenance } : {}) };
+  if (input.creditPace?.active) {
+    const self = input.candidates.find((candidate) => candidate.name === input.current.name);
+    const eligible = (name: string, balance: number | undefined, hasCredits: boolean | undefined, home: string | undefined): boolean =>
+      !!home?.trim() && typeof balance === 'number' && Number.isFinite(balance) && balance > 0
+      && hasCredits !== false && accountThresholds.some((row) => row.name === name
+        && (row.status === 'reached' || row.status === 'threshold-reached'));
+    const currentBalance = input.currentCreditBalance ?? self?.creditBalance;
+    const currentHas = input.currentHasCredits ?? self?.hasCredits;
+    const to = otherCandidates.filter((candidate) => eligible(candidate.name, candidate.creditBalance, candidate.hasCredits, candidate.home))
+      .sort((a, b) => (b.creditBalance! - a.creditBalance!) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))[0];
+    if (eligible(input.current.name, currentBalance, currentHas, self?.home ?? input.current.home)) {
+      return { reason: 'credit-pace', candidateCount, accountThresholds };
+    }
+    if (to) {
+      return { reason: 'credit-pace', candidateCount, accountThresholds, to };
+    }
+  }
   const currentUsageUnknown = input.currentReached === undefined && input.currentUsedPercent == null;
   if (input.currentReached !== true && !currentUsageUnknown && accountThresholds[0]?.status !== 'threshold-reached') {
     return { reason: 'not-reached', candidateCount, accountThresholds };
@@ -271,7 +291,7 @@ export function observeRotation(decision: RotationDecision, from: string): void
     ...(decision.reason === 'disabled' && decision.disabledProvenance
       ? { disabledProvenance: decision.disabledProvenance }
       : {}),
-  }, { level: decision.reason === 'rotated' || decision.reason === 'reset-credit-unknown' ? 'warn' : 'debug' });
+  }, { level: decision.reason === 'rotated' || decision.reason === 'reset-credit-unknown' || (decision.reason === 'credit-pace' && decision.to) ? 'warn' : 'debug' });
   for (const account of decision.accountThresholds ?? []) {
     debug.log('oauth.codex-account', 'rotation-account-threshold', account);
   }
@@ -279,7 +299,8 @@ export function observeRotation(decision: RotationDecision, from: string): void
   if (decision.reason !== 'explicit' && decision.reason !== 'disabled') {
     const fromRow = decision.accountThresholds?.find((a) => a.name === from);
     const toCredit = decision.to?.creditBalance;
-    const why = typeof toCredit === 'number'
+    const why = decision.reason === 'credit-pace' ? '오늘 크레딧 몫을 먼저 쓴다'
+      : typeof toCredit === 'number'
       // 금액은 문장에 넣지 않는다 — 판단 사유는 Live·Trace 카드에 글자로 뜨고 공개 캡처가 문장 속 숫자를 못 가린다(09-28 🅣).
       ? `구독 한도 전부 참 · ${decision.to!.name} 크레딧이 가장 많다`
       : fromRow ? `${from} ${fromRow.usedPercent ?? '?'}% · 임계 ${fromRow.thresholdPercent}%` : `판정 ${decision.reason}`;
@@ -287,7 +308,8 @@ export function observeRotation(decision: RotationDecision, from: string): void
       kind: 'ROUTE',
       what: decision.to ? `codex 계정 ${from} → ${decision.to.name}` : `codex 계정 ${from} 유지 (${decision.reason})`,
       reason: why,
-      purpose: decision.reason === 'credits-allowed' ? '한도가 찼다 — 정책상 크레딧으로 계속'
+      purpose: decision.reason === 'credit-pace' ? '하루 크레딧 몫을 채운 뒤 구독 순서로 복귀'
+        : decision.reason === 'credits-allowed' ? '한도가 찼다 — 정책상 크레딧으로 계속'
         : typeof toCredit === 'number' ? '크레딧을 세 계정에 고르게 · 한 계정이 먼저 마르지 않게' : '구독 한도 보존 · 끊김 없이 계속',
       target: decision.to?.name ?? from,
       refs: { account: decision.to?.name ?? from },
@@ -301,7 +323,7 @@ export function applyRotation(
   current: CodexAccountResolution,
   decision: RotationDecision,
 ): CodexAccountResolution {
-  if ((decision.reason !== 'rotated' && decision.reason !== 'reset-credit-unknown') || !decision.to) return current;
+  if ((decision.reason !== 'rotated' && decision.reason !== 'reset-credit-unknown' && decision.reason !== 'credit-pace') || !decision.to) return current;
   return {
     name: decision.to.name,
     storeKey: decision.to.storeKey,

package/src/oauth/codex-account-store.ts

@@ -13,6 +13,8 @@ import {
 } from './codex-account.js';
 import { authStorePath, defaultCodexHome, listProviders, loadTokens, saveTokens } from './store.js';
 import { readFreshAvailabilityState, quotaSignalDir, readQuotaSignal, readQuotaSignalCredits, readQuotaSignalUsedPercent, readQuotaSignalObservedAt, readQuotaSignalObservedAtRaw } from '../budget/codex-reset-credit-state.js';
+import { creditPaceStatus } from '../budget/codex-credit-pace.js';
+import { loadLlmPolicy } from '../policy/llm-policy.js';
 import { getUserConfig } from '../user-config.js';
 import {
   decideCodexRotation, observeRotation, applyRotation, readCodexAccountRotationConfig, rotatedChildEnv,
@@ -278,6 +280,13 @@ function buildRotationCandidates(path: string, now: number, env: NodeJS.ProcessE
     .filter((c): c is RotationCandidate => c !== null);
 }
 
+function rotationCreditPace(candidates: readonly RotationCandidate[], now: number) {
+  const policy = loadLlmPolicy({ now: new Date(now) }).policy;
+  const balances = Object.fromEntries(candidates.filter((c) => c.creditBalance !== undefined)
+    .map((c) => [c.name, c.creditBalance!]));
+  return creditPaceStatus({ policy, balances, now: new Date(now) });
+}
+
 function formatUsedPercent(value: number | undefined): string {
   return value === undefined ? 'unknown' : `${value}%`;
 }
@@ -517,7 +526,7 @@ export function inspectCodexRotation(
   const rawThreshold = rotationThresholdFromConfig();
   const thresholdPercentByAccount = rotationThresholdsByAccountFromConfig();
   const decision = decideCodexRotation({
-    current, explicit, enabled, disabledProvenance: rotationConfig.state, currentReached, currentUsedPercent, accountOrder: accountOrderFromConfig(), resetCreditAvailability: resetCreditAvailability(currentHome, now), thresholdPercent: rawThreshold, thresholdPercentByAccount, creditsAllowed: codexCreditsAllowedFromConfig(), ...currentCredits, candidates,
+    current, explicit, enabled, disabledProvenance: rotationConfig.state, currentReached, currentUsedPercent, accountOrder: accountOrderFromConfig(), resetCreditAvailability: resetCreditAvailability(currentHome, now), thresholdPercent: rawThreshold, thresholdPercentByAccount, creditsAllowed: codexCreditsAllowedFromConfig(), ...currentCredits, candidates, creditPace: rotationCreditPace(candidates, now),
   });
   // ⛔⭐ 나이는 «만료돼도» 낸다 — 「65분 전」과 「3일 전」은 다른 진단이다(리뷰 must-fix).
   const observedAtByHome: Record<string, number> = {};
@@ -603,6 +612,7 @@ export function resolveCodexAccountForRun(
   const candidates = buildRotationCandidates(path, now, env);
   const currentSignalAttributable = signalAttributableToAccount(currentHomeInfo);
 
+  const creditPace = rotationCreditPace(candidates, now);
   const decision = decideCodexRotation({
     current,
     explicit,
@@ -617,6 +627,13 @@ export function resolveCodexAccountForRun(
     creditsAllowed: codexCreditsAllowedFromConfig(),
     ...currentCreditsInput(currentSignalAttributable ? currentHome : undefined, now),
     candidates,
+    creditPace,
+  });
+  debug.log('codex.rotation', 'credit-pace', {
+    active: creditPace.active,
+    todaySpent: creditPace.todaySpent,
+    target: creditPace.target,
+    to: decision.reason === 'credit-pace' ? decision.to?.name ?? current.name : decision.to?.name,
   });
   observeRotation(decision, current.name);
   const resolved = applyRotation(current, decision);
@@ -726,7 +743,7 @@ export function resolveRunFallback(
   try {
     const snapshot = inspectCodexRotation(env, deps.storePath ? { storePath: deps.storePath } : {});
     let rotation: RotationOutcome;
-    if ((snapshot.reason === 'rotated' || snapshot.reason === 'reset-credit-unknown') && snapshot.to) {
+    if ((snapshot.reason === 'rotated' || snapshot.reason === 'reset-credit-unknown' || snapshot.reason === 'credit-pace') && snapshot.to) {
       // ⛔ 스냅샷은 이름만 준다 — 후보 목록에서 «그 객체»를 되찾는다(홈까지 필요하다).
       const to = snapshot.candidates.find((c) => c.name === snapshot.to);
       rotation = to ? { reason: snapshot.reason, to } : { reason: 'no-candidate' };
@@ -734,6 +751,7 @@ export function resolveRunFallback(
       snapshot.reason === 'explicit'
       || snapshot.reason === 'disabled'
       || snapshot.reason === 'not-reached'
+      || snapshot.reason === 'credit-pace'
       || snapshot.reason === 'reset-credit-available'
       || snapshot.reason === 'no-candidate'
     ) {

package/src/oauth/codex-browser-login.ts

@@ -0,0 +1,173 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import { spawn } from 'node:child_process';
+import { debug } from '../debug/log.js';
+import { CODEX_OAUTH_CLIENT_ID, CODEX_OAUTH_TOKEN_URL } from './codex.js';
+import { expiresAtFromSeconds, saveTokens, type ProviderAuthState } from './store.js';
+
+const AUTHORIZE_URL = 'https://auth.openai.com/oauth/authorize';
+const DEFAULT_PORT = 1455;
+const TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface CodexBrowserLoginOpts {
+  fetchImpl?: typeof fetch;
+  openBrowser?: (url: string) => boolean | Promise<boolean>;
+  timeoutMs?: number;
+  preferredPort?: number;
+  mirrorCodex?: boolean;
+}
+
+export function browserLaunchCommand(url: string, platform: NodeJS.Platform = process.platform): { command: string; args: string[] } {
+  if (platform === 'win32') {
+    // Use the Windows URL handler directly; cmd.exe expands & and % even inside OAuth URLs.
+    return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
+  }
+  return { command: platform === 'darwin' ? 'open' : 'xdg-open', args: [url] };
+}
+
+/** A launcher that exits non-zero this soon has failed; one still running (or exiting 0) handed the URL off. */
+const LAUNCH_GRACE_MS = 1_000;
+
+function openBrowser(url: string): Promise<boolean> {
+  const { command, args } = browserLaunchCommand(url);
+  return new Promise(resolve => {
+    let settled = false;
+    const settle = (ok: boolean) => { if (!settled) { settled = true; resolve(ok); } };
+    try {
+      const child = spawn(command, args, { stdio: 'ignore', detached: true });
+      child.once('error', () => settle(false));
+      child.once('exit', code => settle(code === 0));
+      child.once('spawn', () => {
+        const grace = setTimeout(() => { child.unref(); settle(true); }, LAUNCH_GRACE_MS);
+        grace.unref?.();
+        child.once('exit', () => clearTimeout(grace));
+      });
+    } catch { settle(false); }
+  });
+}
+
+function listen(server: Server, port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+/** Local OAuth callback, independent of a bundled or PATH Codex executable. */
+export async function loginWithCodexBrowser(opts: CodexBrowserLoginOpts = {}): Promise<ProviderAuthState> {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const state = randomBytes(32).toString('base64url');
+  let port = opts.preferredPort ?? DEFAULT_PORT;
+  let resolveCallback!: (value: ProviderAuthState) => void;
+  let rejectCallback!: (reason: Error) => void;
+  const callback = new Promise<ProviderAuthState>((resolve, reject) => {
+    resolveCallback = resolve;
+    rejectCallback = reject;
+  });
+  void callback.catch(() => {});
+  let settled = false;
+  let handling = false;
+  const tokenAbort = new AbortController();
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+    if (req.method !== 'GET' || url.pathname !== '/auth/callback') {
+      res.writeHead(404).end();
+      return;
+    }
+    debug.log('oauth.codex-browser', 'callback', { port });
+    if (handling || settled) { res.writeHead(409).end(); return; }
+    if (url.searchParams.get('state') !== state) {
+      res.writeHead(400).end('Invalid login state.');
+      return;
+    }
+    const code = url.searchParams.get('code');
+    if (!code || url.searchParams.has('error')) {
+      res.writeHead(400).end('Login failed. Return to the terminal.');
+      rejectCallback(new Error('authorization-denied'));
+      return;
+    }
+    handling = true;
+    void (async () => {
+      try {
+        const response = await (opts.fetchImpl ?? fetch)(CODEX_OAUTH_TOKEN_URL, {
+          method: 'POST',
+          signal: tokenAbort.signal,
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+          body: new URLSearchParams({
+            grant_type: 'authorization_code', code, redirect_uri: `http://localhost:${port}/auth/callback`,
+            client_id: CODEX_OAUTH_CLIENT_ID, code_verifier: verifier,
+          }).toString(),
+        });
+        if (!response.ok) throw new Error('token-exchange');
+        const token = await response.json() as {
+          access_token?: string; refresh_token?: string; id_token?: string;
+          expires_in?: number; scope?: string; token_type?: string;
+        };
+        if (!token.access_token || !token.refresh_token) throw new Error('token-exchange');
+        if (settled) { res.writeHead(410).end(); return; }
+        const saved = saveTokens('openai-codex', {
+          accessToken: token.access_token,
+          refreshToken: token.refresh_token,
+          ...(token.id_token ? { idToken: token.id_token } : {}),
+          expiresAt: expiresAtFromSeconds(token.expires_in),
+          scope: token.scope,
+          tokenType: token.token_type ?? 'Bearer',
+        }, { authMode: 'chatgpt', mirrorCodex: opts.mirrorCodex });
+        debug.log('oauth.codex-browser', 'exchanged', { port });
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+          .end('<!doctype html><html lang="ko"><meta charset="utf-8"><body>로그인됨 — 터미널로 돌아가세요</body></html>');
+        resolveCallback(saved);
+      } catch {
+        res.writeHead(400).end('Login failed. Return to the terminal.');
+        rejectCallback(new Error('token-exchange'));
+      }
+    })();
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = () => rejectCallback(new Error('cancelled'));
+  const onExit = () => server.close();
+  const onServerError = () => rejectCallback(new Error('port-unavailable'));
+  let listening = false;
+  try {
+    try { await listen(server, port); }
+    catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EADDRINUSE' || port === 0) throw err;
+      await listen(server, 0);
+    }
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('port-unavailable');
+    listening = true;
+    port = address.port;
+    server.on('error', onServerError);
+    process.once('SIGINT', cancel);
+    process.once('exit', onExit);
+    timer = setTimeout(() => rejectCallback(new Error('timeout')), opts.timeoutMs ?? TIMEOUT_MS);
+    const authorize = new URL(AUTHORIZE_URL);
+    for (const [key, value] of Object.entries({
+      client_id: CODEX_OAUTH_CLIENT_ID, redirect_uri: `http://localhost:${port}/auth/callback`,
+      response_type: 'code', code_challenge: challenge, code_challenge_method: 'S256', state,
+      scope: 'openid profile email offline_access', id_token_add_organizations: 'true',
+      codex_cli_simplified_flow: 'true', originator: 'codex_cli_rs',
+    })) authorize.searchParams.set(key, value);
+    debug.log('oauth.codex-browser', 'started', { port });
+    if (!await (opts.openBrowser ?? openBrowser)(authorize.toString())) throw new Error('browser-unavailable');
+    return await callback;
+  } catch (err) {
+    const reason = err instanceof Error && ['timeout', 'cancelled', 'browser-unavailable', 'authorization-denied', 'token-exchange'].includes(err.message)
+      ? err.message : 'port-unavailable';
+    debug.log('oauth.codex-browser', 'failed', { port, reason });
+    throw new Error(`codex browser login failed: ${reason}`);
+  } finally {
+    settled = true;
+    tokenAbort.abort();
+    if (timer) clearTimeout(timer);
+    process.off('SIGINT', cancel);
+    process.off('exit', onExit);
+    if (listening) server.close();
+    server.off('error', onServerError);
+  }
+}

package/src/oauth/codex.ts

@@ -121,6 +121,8 @@ interface UserCodeResponse {
   device_auth_id: string;
   interval?: number;
   expires_in?: number;
+  verification_uri_complete?: string;
+  verification_uri?: string;
 }
 
 interface PollSuccessResponse {
@@ -278,7 +280,8 @@ export async function loginWithCodex(opts: CodexLoginOpts = {}): Promise<Provide
   const userCode = await requestDeviceCode({ fetchImpl });
   const serverInterval = typeof userCode.interval === 'number' ? userCode.interval * 1000 : 0;
   const pollInterval = Math.max(reportedInterval, serverInterval || 0);
-  onProgress({ type: 'user_code', userCode: userCode.user_code, loginUrl: CODEX_DEVICE_LOGIN_URL });
+  onProgress({ type: 'user_code', userCode: userCode.user_code,
+    loginUrl: userCode.verification_uri_complete || userCode.verification_uri || CODEX_DEVICE_LOGIN_URL });
 
   // 2) Poll until ready or timeout.
   const startedAt = Date.now();

package/src/oauth/fallback-chain.ts

@@ -69,8 +69,8 @@ export function normalizeFallbackChain(
 /** 회전 판정이 낸 이유 — `codex-account-rotation.ts` 의 `RotationReason` 과 같은 어휘.
  *  ⛔ 그쪽 타입이 비공개라 구조적으로 받는다(그 파일의 리뷰 규율: dead export 금지). */
 export type RotationOutcome =
-  | { readonly reason: 'rotated' | 'reset-credit-unknown'; readonly to: RotationCandidate }
-  | { readonly reason: 'explicit' | 'disabled' | 'not-reached' | 'reset-credit-available' | 'no-candidate' };
+  | { readonly reason: 'rotated' | 'reset-credit-unknown' | 'credit-pace'; readonly to: RotationCandidate }
+  | { readonly reason: 'explicit' | 'disabled' | 'not-reached' | 'credit-pace' | 'reset-credit-available' | 'no-candidate' };
 
 export type FallbackDecision =
   /** codex 계정을 갈아탄다(종전 동작). */
@@ -156,14 +156,14 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
     return stepAfter(chain, currentStep, grokAvailable, grokQuota, 'chain-exhausted');
   }
   if (rotation.reason === 'explicit') return { action: 'stay', why: 'explicit' };
-  if (rotation.reason === 'not-reached') {
+  if (rotation.reason === 'not-reached' || (rotation.reason === 'credit-pace' && !('to' in rotation))) {
     return { action: 'stay', why: 'not-reached' };
   }
   if (rotation.reason === 'reset-credit-available' && stayOnResetCreditAvailable) {
     return { action: 'stay', why: 'reset-credit-available' };
   }
 
-  if (rotation.reason === 'rotated' || rotation.reason === 'reset-credit-unknown') {
+  if (rotation.reason === 'rotated' || rotation.reason === 'reset-credit-unknown' || (rotation.reason === 'credit-pace' && 'to' in rotation)) {
     // 회전이 답을 냈는데 체인이 codex-rotate 를 «빼» 놨다면 그 뜻을 존중하고
     // 다음 칸으로 간다(회전을 원치 않는 구성).
     if (chain.includes('codex-rotate')) return { action: 'codex-rotate', to: rotation.to };
@@ -172,7 +172,7 @@ export function decideFallback(input: FallbackInput): FallbackDecision {
 
   // no-candidate | disabled | reset-credit-available(기본) — codex 축이 끝났다. 다음 칸을 본다.
   // ⛔ 다음 칸이 «없을 때»의 이름만 고른다. 진행(stepAfterCodex)은 그대로다.
-  const fallbackWhy = stayReasonWhenCodexAxisEnds(rotation.reason);
+  const fallbackWhy = stayReasonWhenCodexAxisEnds(rotation.reason === 'credit-pace' ? 'no-candidate' : rotation.reason);
   return stepAfterCodex(chain, grokAvailable, grokQuota, fallbackWhy);
 }