sprag-cli 3.46.2 → 3.47.0

package/README.ko.md

@@ -109,6 +109,8 @@ harness 5/5 + ratchet을 실제 적용한 전후 비교입니다 (저자 Claude
 | [라우터가 아닌 이유](https://github.com/rootstudioyaml/sprag/blob/main/docs/NOT-A-ROUTER.ko.md) | 실시간 라우팅이 캐시를 깨서 비용을 키우는 구조 |
 | [게이트웨이와 환경](https://github.com/rootstudioyaml/sprag/blob/main/docs/GATEWAYS.ko.md) | Bedrock·Vertex·LiteLLM, 가격표, FAQ, 동작 원리 |
 
+LiteLLM 게이트웨이 환경에서는 `sprag profile-map --refresh` 가 게이트웨이의 `GET /model/info` 에서 모델 별칭을 바로 읽어 오므로, route-scan 이 위임 투표가 쌓이길 기다리거나 `profile-map.json` 을 손으로 편집할 필요가 없어졌습니다. 이 갱신은 LiteLLM 예산 게이지와 같은 5분 점검·24시간 캐시 주기에 얹혀 돌아갑니다. 인증 토큰은 저장하지 않으며, 호출 시점마다 `apiKeyHelper` 에서 읽어 그 헬퍼의 수명 그대로 만료되게 둡니다. 자세한 내용은 [route-scan](https://github.com/rootstudioyaml/sprag/blob/main/docs/ROUTE_SCAN.md) 문서에 있습니다.
+
 ## 릴리스 노트
 
 전체 내역은 [CHANGELOG.md](./CHANGELOG.md)로 옮겼습니다. 최근 변경은 다음과 같습니다.

package/README.md

@@ -109,6 +109,8 @@ Every subcommand, flag and the output-language setting: [command reference](http
 | [Not a router](https://github.com/rootstudioyaml/sprag/blob/main/docs/NOT-A-ROUTER.md) | Why realtime routing breaks the cache and costs more |
 | [Gateways & environment](https://github.com/rootstudioyaml/sprag/blob/main/docs/GATEWAYS.md) | Bedrock, Vertex, LiteLLM budgets, pricing table, FAQ, how it works |
 
+Behind a LiteLLM gateway, `sprag profile-map --refresh` now reads model aliases straight from the gateway's own `GET /model/info`, so route-scan no longer needs to wait on learned votes or a hand-edited `profile-map.json`. The refresh rides the same 5-minute check and 24-hour cache as the LiteLLM budget gauge. It never stores your auth token: each refresh reads it from `apiKeyHelper` at call time and lets it expire on the helper's own schedule. Details: [route-scan](https://github.com/rootstudioyaml/sprag/blob/main/docs/ROUTE_SCAN.md).
+
 ## Release notes
 
 The full history moved to [CHANGELOG.md](./CHANGELOG.md) (Korean; version headings and command names are language-neutral). Recent changes:

package/bin/cli.js

@@ -87,7 +87,7 @@ function readUpdateChip() {
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
   'doc2md', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
-  'seed', 'litellm-budget', 'feedback',
+  'seed', 'litellm-budget', 'profile-map', 'feedback',
 ]);
 
 const USAGE = `sprag — Claude Code token usage, cache health, and model routing
@@ -99,6 +99,7 @@ Usage:
   sprag --format csv       CSV output
   sprag --project myproj   filter by project
   sprag route-scan         detect recurring easy work → delegation candidates
+  sprag profile-map        show/refresh the gateway model map (LiteLLM /model/info)
   sprag install            set up skill/hooks/statusline
   sprag install --yes      take the defaults without asking
   sprag uninstall          remove everything install added
@@ -296,12 +297,22 @@ async function main() {
   //   sprag litellm-budget --json     # 캐시 원본 JSON 출력
   //   sprag litellm-budget --refresh  # 지금 프록시에 물어봄 (detached 자식이 사용)
   if (args[0] === 'litellm-budget') {
-    const { gatewayBase, readBudgetState, refreshBudgetState, formatBudgetReport } =
+    const { gatewayBase, readBudgetState, refreshBudgetState, formatBudgetReport, resolveKey } =
       await import('../src/litellm-budget.js');
     const quiet = hasFlag('--quiet');
     if (hasFlag('--refresh')) {
       try {
-        const next = await refreshBudgetState();
+        // apiKeyHelper 가 토큰 수명(TTL)을 소유합니다. 헬퍼를 한 번만 불러 그
+        // 키를 예산 갱신과 게이트웨이 모델맵 갱신 양쪽에 재사용합니다. 갱신
+        // 경로마다 resolveKey() 를 다시 부르면 사본을 만드는 셈이 되고, 헬퍼
+        // 호출 횟수도 그만큼 늘어납니다.
+        const key = resolveKey();
+        let next = null;
+        if (key) {
+          next = await refreshBudgetState(process.env, fetch, key);
+          const { maybeRefreshGatewayModelMap } = await import('../src/litellm-models.js');
+          await maybeRefreshGatewayModelMap({ base: gatewayBase(), key });
+        }
         if (!quiet) console.log(JSON.stringify(next, null, 2));
       } catch (e) {
         debug('litellm-budget:refresh', e);
@@ -334,6 +345,15 @@ async function main() {
     return;
   }
 
+  // Subcommand: profile-map · LiteLLM 게이트웨이의 프로파일 ID → 모델 별칭
+  // 매핑을 보여 주거나(GET /model/info) 갱신합니다.
+  //   sprag profile-map            # 캐시된 게이트웨이 모델맵 출력
+  //   sprag profile-map --json     # 캐시 원본 JSON 출력
+  //   sprag profile-map --refresh  # 지금 프록시에 물어봄 (사람이 직접 실행)
+  if (args[0] === 'profile-map') {
+    return (await import('../src/commands/profile-map.js')).run({ args, hasFlag });
+  }
+
   // Subcommand: upgrade — run the install command that matches how this copy
   // got here, then confirm the new version.
   //   sprag upgrade          # install the latest release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.46.2",
+  "version": "3.47.0",
   "description": "Sprag - a quality ratchet harness for AI coding agents: model-fitting delegation, ratchet rules, doc2md, Korean style gate. Same tool as claude-token-saver, under its new name.",
   "type": "module",
   "bin": {

package/src/commands/profile-map.js

@@ -0,0 +1,164 @@
+/**
+ * Subcommand: profile-map. LiteLLM 게이트웨이의 프로파일 ID → 모델 계열 매핑을
+ * 보여 주거나 갱신합니다.
+ *
+ *   sprag profile-map            # 캐시된 매핑을 사람이 읽을 수 있게 출력
+ *   sprag profile-map --json     # profile-map.json 원본을 그대로 출력
+ *   sprag profile-map --refresh  # LiteLLM GET /model/info 를 지금 호출해 캐시를 갱신
+ *   sprag profile-map --quiet    # 위 어느 모드든 출력을 억제 (스크립트/자식 프로세스용)
+ *
+ * 왜 이 명령이 필요한가: model-alias.js 의 학습 경로(투표)는 서브에이전트
+ * 실행이 MIN_VOTES 건 이상 쌓여야 판정이 서므로, 새 프로파일 ID 나 사용량이
+ * 적은 티어는 오랫동안(또는 영원히) role=null 로 남는다. 반면 LiteLLM
+ * `/model/info` 는 게이트웨이가 이미 알고 있는 배포 목록을 즉시 돌려주므로,
+ * 이 명령으로 그 매핑을 캐시해 두면 학습을 기다릴 필요가 없다. 실제 판정은
+ * model-alias.js 의 resolveModelAlias() 가 하고, 이 명령은 그 판정에 쓰이는
+ * 세 출처(override/gateway/learned)를 사람이 확인할 수 있게 보여 줄 뿐이다.
+ *
+ * 왜 --refresh 에서만 resolveKey() 를 부르는가: apiKeyHelper 가 인증 토큰의
+ * 수명(TTL)을 소유한다. 이 명령의 읽기 경로(플래그 없음/--json)는 캐시 파일만
+ * 보므로 키가 전혀 필요 없고, --refresh 는 사람이 터미널에서 직접 실행하는
+ * 경로라서 헬퍼가 Okta 로그인 창을 띄우더라도 괜찮다(사용자 지시). 얻은 키는
+ * fetch 요청 헤더에만 쓰고, 화면에 출력하거나 파일에 쓰지 않는다.
+ */
+
+export async function run({ args, hasFlag }) {
+  const { userLanguage } = await import('../config.js');
+  const { loadProfileMap, aliasForRole, MIN_VOTES } = await import('../model-alias.js');
+  const { gatewayBase, resolveKey } = await import('../gateway-auth.js');
+  const { readGatewayModelMap, refreshGatewayModelMap } = await import('../litellm-models.js');
+
+  const lang = userLanguage();
+  const ko = lang === 'ko';
+  const quiet = hasFlag('--quiet');
+  const say = (line) => { if (!quiet) console.log(line); };
+
+  const base = gatewayBase();
+  if (!base) {
+    // 오류가 아니다: 공식 API 를 직접 쓰는 사용자에게는 이 명령이 원래 할 일이
+    // 없다. --refresh 와 --json 도 base 없이는 의미가 없으므로 여기서 함께
+    // 걸러낸다.
+    say(ko
+      ? '게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL 필요). LiteLLM 등 게이트웨이 뒤에서 실행할 때만 쓰는 명령입니다.'
+      : 'No gateway detected (ANTHROPIC_BASE_URL required). This command only matters behind a gateway such as LiteLLM.');
+    return;
+  }
+
+  if (hasFlag('--refresh')) {
+    const key = resolveKey();
+    if (!key) {
+      say(ko
+        ? 'apiKeyHelper 가 토큰을 내주지 못했습니다. 인증을 마친 뒤 다시 실행하십시오.'
+        : 'apiKeyHelper did not return a token. Authenticate, then run this again.');
+      process.exitCode = 1;
+      return;
+    }
+    const result = await refreshGatewayModelMap({ base, key });
+    if (!result) {
+      say(ko
+        ? `LiteLLM 에서 모델 정보를 가져오지 못했습니다 (GET ${base}/model/info). CTS_DEBUG=1 로 다시 실행하면 원인이 보입니다.`
+        : `Could not fetch model info from LiteLLM (GET ${base}/model/info). Re-run with CTS_DEBUG=1 to see why.`);
+      process.exitCode = 1;
+      return;
+    }
+    const resolved = Object.keys(result.aliases).length;
+    say(ko
+      ? `배포 ${result.count}건 중 ${resolved}개 키를 해석했습니다${result.skipped.length ? ` (미해석 ${result.skipped.length}건)` : ''}.`
+      : `Resolved ${resolved} key(s) out of ${result.count} deployment(s)${result.skipped.length ? ` (${result.skipped.length} unresolved)` : ''}.`);
+    if (result.skipped.length) {
+      say(ko
+        ? `  미해석 model_name: ${result.skipped.join(', ')}`
+        : `  Unresolved model_name: ${result.skipped.join(', ')}`);
+    }
+    return;
+  }
+
+  const map = loadProfileMap();
+  const gatewayMap = readGatewayModelMap();
+
+  if (hasFlag('--json')) {
+    say(JSON.stringify(map, null, 2));
+    return;
+  }
+
+  say(ko ? `게이트웨이: ${base}` : `Gateway: ${base}`);
+
+  if (gatewayMap) {
+    const fetchedMs = Date.parse(gatewayMap.fetchedAt);
+    const ageMin = Number.isFinite(fetchedMs) ? Math.max(0, Math.round((Date.now() - fetchedMs) / 60000)) : null;
+    const resolved = Object.keys(gatewayMap.aliases || {}).length;
+    say(ko
+      ? `조회 ${ageMin === null ? '알 수 없음' : `${ageMin}분 전`} · 배포 ${gatewayMap.count}건 · 해석된 키 ${resolved}개`
+      : `checked ${ageMin === null ? 'unknown' : `${ageMin}m ago`} · ${gatewayMap.count} deployment(s) · ${resolved} key(s) resolved`);
+  } else {
+    say(ko
+      ? '게이트웨이 모델맵이 아직 없습니다. `sprag profile-map --refresh` 로 지금 가져오십시오.'
+      : 'No gateway model map cached yet. Fetch it now with `sprag profile-map --refresh`.');
+  }
+
+  const overrideEntries = Object.entries(map.modelAliases || {});
+  if (overrideEntries.length) {
+    say(ko ? '\n사용자 매핑 (modelAliases):' : '\nUser overrides (modelAliases):');
+    for (const [pattern, alias] of overrideEntries) {
+      say(`  ${pattern} → ${alias} (override)`);
+    }
+  }
+
+  const gwAliases = gatewayMap?.aliases || {};
+  const learned = map.learned || {};
+  // Set 으로 합치는 이유: 같은 프로파일 ID 가 두 출처 모두에 나타날 수 있고,
+  // 그때 서로 다른 답을 준다면 그 자체가 사용자에게 알려야 할 신호다(학습이
+  // 틀렸거나 게이트웨이 설정이 바뀌었다는 뜻).
+  const keys = [...new Set([...Object.keys(gwAliases), ...Object.keys(learned)])].sort();
+
+  if (keys.length) {
+    say(ko ? '\n게이트웨이 · 학습 매핑:' : '\nGateway & learned mappings:');
+    for (const key of keys) {
+      const gwAlias = gwAliases[key];
+      const entry = learned[key];
+
+      if (gwAlias) {
+        say(`  ${key} → ${gwAlias} (gateway)`);
+        if (entry?.role) {
+          const learnedAlias = aliasForRole(entry.role);
+          if (learnedAlias && learnedAlias !== gwAlias) {
+            say(ko
+              ? `    ⚠ 학습 결과는 ${learnedAlias} 였습니다. 학습이 틀렸거나 게이트웨이 설정이 바뀌었을 수 있습니다.`
+              : `    ⚠ the learned result was ${learnedAlias}. Either the learning was wrong, or the gateway config changed.`);
+          }
+        } else if (entry && !entry.role) {
+          say(ko
+            ? `    학습은 표 ${entry.total || 0}개로 판정 대기였지만, 게이트웨이가 이미 해석했으므로 더 이상 문제되지 않습니다.`
+            : `    Learning was still undecided at ${entry.total || 0} vote(s), but the gateway already resolves this, so it is no longer an issue.`);
+        }
+        continue;
+      }
+
+      if (entry?.role) {
+        const learnedAlias = aliasForRole(entry.role);
+        say(learnedAlias
+          ? `  ${key} → ${learnedAlias} (learned · ${entry.role})`
+          : (ko ? `  ${key} → ${entry.role} 역할 · 별칭 미확정 (learned)` : `  ${key} → ${entry.role} role · alias undecided (learned)`));
+      } else if (entry) {
+        say(ko
+          ? `  ${key} → 표 ${entry.total || 0}개 · 판정 대기 (기준 ${MIN_VOTES}개, learned)`
+          : `  ${key} → ${entry.total || 0} vote(s) · undecided (needs ${MIN_VOTES}, learned)`);
+      }
+    }
+  }
+
+  if (!overrideEntries.length && !keys.length) {
+    say(ko
+      ? '\n등록된 매핑이 없습니다.'
+      : '\nNo mappings recorded yet.');
+  }
+
+  if (gatewayMap?.skipped?.length) {
+    say(ko
+      ? `\n게이트웨이가 계열명을 알아내지 못한 배포: ${gatewayMap.skipped.join(', ')}.`
+      : `\nDeployments the gateway could not name a family for: ${gatewayMap.skipped.join(', ')}.`);
+    say(ko
+      ? '  profile-map.json 의 modelAliases 에 해당 이름을 직접 매핑하십시오.'
+      : '  Map those names directly under modelAliases in profile-map.json.');
+  }
+}

package/src/commands/route-scan.js

@@ -183,15 +183,19 @@ export async function run({ args, hasFlag, numArg }) {
         const { MIN_VOTES } = await import('../model-alias.js');
         const learning = scan.unresolvedRuns < MIN_VOTES;
         const remedyKo = learning
-          ? `\n  위임이 ${MIN_VOTES}건 이상 쌓이면 자동으로 해석될 수 있습니다. 그때까지 기다렸다가 다시 확인하고,`
-            + '\n  게이트웨이가 모델 이름을 아예 알려 주지 않는 환경이라면 profile-map.json 의 modelAliases 에'
-            + '\n  해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.'
-          : '\n  profile-map.json 의 modelAliases 에 해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.';
+          ? `\n  위임이 ${MIN_VOTES}건 이상 쌓이면 자동으로 해석될 수 있습니다. 그때까지 기다리는 동안`
+            + '\n  sprag profile-map --refresh 를 먼저 실행해 보십시오. LiteLLM 게이트웨이라면 배포 목록에서'
+            + '\n  매핑을 곧바로 가져옵니다. 그래도 남는 ID 는 profile-map.json 의 modelAliases 에 직접'
+            + '\n  매핑한 뒤 route-scan --refresh 를 실행하십시오.'
+          : '\n  sprag profile-map --refresh 를 먼저 실행해 보십시오. LiteLLM 게이트웨이라면 배포 목록에서 매핑을 곧바로 가져옵니다.'
+            + '\n  그래도 남는 ID 는 profile-map.json 의 modelAliases 에 직접 매핑한 뒤 route-scan --refresh 를 실행하십시오.';
         const remedyEn = learning
-          ? `\n  These may resolve on their own once ${MIN_VOTES} or more delegated runs accumulate — check again then.`
-            + '\n  If the gateway never reports a model name at all, map the id under modelAliases in'
+          ? `\n  These may resolve on their own once ${MIN_VOTES} or more delegated runs accumulate; check again then.`
+            + '\n  Meanwhile, try sprag profile-map --refresh first: on a LiteLLM gateway it pulls the mapping'
+            + '\n  straight from the deployment list. Anything still left over, map it under modelAliases in'
             + '\n  profile-map.json and run route-scan --refresh.'
-          : '\n  Map it under modelAliases in profile-map.json, then run route-scan --refresh.';
+          : '\n  Try sprag profile-map --refresh first: on a LiteLLM gateway it pulls the mapping straight from the deployment list.'
+            + '\n  Anything still left over, map it under modelAliases in profile-map.json and run route-scan --refresh.';
         console.log(lang === 'ko'
           ? `\n⚠ 해석되지 않은 모델 ID 때문에 위임 ${scan.unresolvedRuns}건이 집계에서 제외됐습니다${ids ? ` (${ids})` : ''}.` + remedyKo
           : `\n⚠ ${scan.unresolvedRuns} delegated run(s) were excluded — unpriceable model id${ids ? ` (${ids})` : ''}.` + remedyEn);

package/src/gateway-auth.js

@@ -0,0 +1,86 @@
+/**
+ * gateway-auth: gateway address detection + auth-token resolution, split out
+ * as a leaf module so other modules can read the LiteLLM gateway's address
+ * and key without risking a circular import.
+ *
+ * Why this file exists: src/formatters/statusline.js imports MIN_VOTES from
+ * src/model-alias.js, and src/litellm-budget.js imports from
+ * formatters/statusline.js. If model-alias.js also needed gatewayBase() from
+ * litellm-budget.js (to resolve gateway-supplied aliases), the import graph
+ * would close a cycle: model-alias.js → litellm-budget.js →
+ * formatters/statusline.js → model-alias.js. This module carries no
+ * dependency on either side of that cycle, so both litellm-budget.js and
+ * model-alias.js can import it safely.
+ *
+ * This module never persists the token it resolves. apiKeyHelper owns that
+ * token's lifecycle (short TTL, refreshed on its own schedule); a cached
+ * copy here would drift out of sync with that lifecycle. Callers receive the
+ * key as a return value only and are expected to pass it along as a plain
+ * argument, not to write it to disk, argv, logs, or error messages.
+ */
+
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { debug } from './debug.js';
+
+export const HELPER_TIMEOUT_MS = 10000;
+
+/**
+ * 게이트웨이 주소만 판정합니다. 캐시만 읽는 경로는 키가 필요하지 않으므로,
+ * 키 확보와 주소 판정을 분리해 둡니다. apiKeyHelper 로만 인증하는 환경에는
+ * 환경변수에 토큰이 없어서, 키를 함께 요구하면 렌더 경로가 통째로 탈락합니다.
+ */
+export function gatewayBase(env = process.env) {
+  const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
+  if (!base) return null;
+  // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
+  if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
+  return base;
+}
+
+/**
+ * Claude Code 와 같은 방식으로 apiKeyHelper 를 실행해 토큰을 얻습니다.
+ * 환경변수에 토큰을 두지 않고 헬퍼 스크립트로 매번 발급받는 구성이 공식 인증
+ * 방식 가운데 하나이며, 그 구성에서는 statusline 자식 프로세스의 process.env
+ * 안에 토큰이 존재하지 않습니다.
+ *
+ * 헬퍼 실행은 비용이 있으므로 갱신 경로(5분에 한 번 뜨는 detached 자식)에서만
+ * 부릅니다. 수 초 간격으로 도는 렌더 경로에서 부르면 통계선이 그만큼 느려집니다.
+ */
+export function keyFromApiKeyHelper(cwd = process.cwd()) {
+  const candidates = [
+    join(cwd, '.claude', 'settings.local.json'),
+    join(cwd, '.claude', 'settings.json'),
+    join(homedir(), '.claude', 'settings.json'),
+  ];
+  for (const p of candidates) {
+    let helper;
+    try {
+      helper = JSON.parse(readFileSync(p, 'utf8'))?.apiKeyHelper;
+    } catch {
+      continue;
+    }
+    if (typeof helper !== 'string' || !helper.trim()) continue;
+    try {
+      const out = execSync(helper, {
+        encoding: 'utf8',
+        timeout: HELPER_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      // 진행 로그를 함께 출력하는 헬퍼가 있으므로 마지막 비어 있지 않은 줄을 취합니다.
+      const token = out.trim().split(/\r?\n/).filter(Boolean).pop();
+      if (token) return token.trim();
+    } catch (e) {
+      debug('gateway-auth:helper', e);
+    }
+  }
+  return null;
+}
+
+/** 환경변수 토큰을 먼저 보고, 없으면 apiKeyHelper 로 내려갑니다. */
+export function resolveKey(env = process.env) {
+  const direct = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
+  return direct || keyFromApiKeyHelper();
+}

package/src/litellm-budget.js

@@ -15,42 +15,39 @@
  * 엔드포인트는 LiteLLM의 `GET {base}/key/info` 이며, 호출한 키 자신의 정보를
  * 돌려줍니다. 응답의 info.max_budget / info.spend / info.budget_reset_at 을
  * 사용합니다. max_budget 이 null 이면(무제한 키) 게이지를 만들지 않습니다.
+ *
+ * 이 파일은 resolveKey() 가 돌려준 토큰을 캐시 파일에 쓰지 않습니다. 그 키는
+ * apiKeyHelper 가 소유한 TTL 을 그대로 따라야 하므로, 여기서 사본을 만들면
+ * 헬퍼의 만료·재발급 주기와 어긋납니다(사용자 지시).
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
 import { gaugeBar, formatMoney } from './formatters/statusline.js';
 import { labelForKey } from './window-labels.js';
 import { formatResetClock } from './format-time.js';
 import { cliEntryPath } from './update-check.js';
 import { debug } from './debug.js';
+// 게이트웨이 주소 판정과 키 확보는 leaf 모듈로 옮겼습니다: model-alias.js 가
+// 게이트웨이 별칭을 조회하려면 이 함수들이 필요한데, model-alias.js 가 이
+// 파일을 직접 import 하면 model-alias.js → litellm-budget.js →
+// formatters/statusline.js → model-alias.js 순환이 생깁니다. 이 파일은 기존
+// 호출부(예: bin/cli.js) 와의 호환을 위해 같은 이름으로 재수출만 합니다.
+import { HELPER_TIMEOUT_MS, gatewayBase, keyFromApiKeyHelper, resolveKey } from './gateway-auth.js';
+
+export { HELPER_TIMEOUT_MS, gatewayBase, keyFromApiKeyHelper, resolveKey };
 
 // 예산은 분 단위로 변하지 않습니다. 5분이면 게이지 용도로 충분히 신선하고,
 // 통계선 렌더(수 초 간격)가 프록시를 두들기지 않습니다.
 const CHECK_INTERVAL_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 5000;
-const HELPER_TIMEOUT_MS = 10000;
 
 export function budgetStatePath() {
   return join(userDataDir(), 'litellm-budget.json');
 }
 
-/**
- * 게이트웨이 주소만 판정합니다. 캐시만 읽는 경로는 키가 필요하지 않으므로,
- * 키 확보와 주소 판정을 분리해 둡니다. apiKeyHelper 로만 인증하는 환경에는
- * 환경변수에 토큰이 없어서, 키를 함께 요구하면 렌더 경로가 통째로 탈락합니다.
- */
-export function gatewayBase(env = process.env) {
-  const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
-  if (!base) return null;
-  // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
-  if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
-  return base;
-}
-
 /** 게이트웨이 주소와 키를 함께 돌려줍니다. 둘 중 하나라도 없으면 null. */
 export function gatewayEnv(env = process.env) {
   const base = gatewayBase(env);
@@ -60,51 +57,6 @@ export function gatewayEnv(env = process.env) {
   return { base, key };
 }
 
-/**
- * Claude Code 와 같은 방식으로 apiKeyHelper 를 실행해 토큰을 얻습니다.
- * 환경변수에 토큰을 두지 않고 헬퍼 스크립트로 매번 발급받는 구성이 공식 인증
- * 방식 가운데 하나이며, 그 구성에서는 statusline 자식 프로세스의 process.env
- * 안에 토큰이 존재하지 않습니다.
- *
- * 헬퍼 실행은 비용이 있으므로 갱신 경로(5분에 한 번 뜨는 detached 자식)에서만
- * 부릅니다. 수 초 간격으로 도는 렌더 경로에서 부르면 통계선이 그만큼 느려집니다.
- */
-export function keyFromApiKeyHelper(cwd = process.cwd()) {
-  const candidates = [
-    join(cwd, '.claude', 'settings.local.json'),
-    join(cwd, '.claude', 'settings.json'),
-    join(homedir(), '.claude', 'settings.json'),
-  ];
-  for (const p of candidates) {
-    let helper;
-    try {
-      helper = JSON.parse(readFileSync(p, 'utf8'))?.apiKeyHelper;
-    } catch {
-      continue;
-    }
-    if (typeof helper !== 'string' || !helper.trim()) continue;
-    try {
-      const out = execSync(helper, {
-        encoding: 'utf8',
-        timeout: HELPER_TIMEOUT_MS,
-        stdio: ['ignore', 'pipe', 'ignore'],
-      });
-      // 진행 로그를 함께 출력하는 헬퍼가 있으므로 마지막 비어 있지 않은 줄을 취합니다.
-      const token = out.trim().split(/\r?\n/).filter(Boolean).pop();
-      if (token) return token.trim();
-    } catch (e) {
-      debug('litellm-budget:helper', e);
-    }
-  }
-  return null;
-}
-
-/** 환경변수 토큰을 먼저 보고, 없으면 apiKeyHelper 로 내려갑니다. */
-export function resolveKey(env = process.env) {
-  const direct = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
-  return direct || keyFromApiKeyHelper();
-}
-
 export function readBudgetState() {
   try {
     const s = JSON.parse(readFileSync(budgetStatePath(), 'utf8'));
@@ -306,17 +258,22 @@ export function pickBudgetSource(keyInfo, userInfo) {
  * 실제로 LiteLLM에 물어보고 캐시를 갱신합니다. detached 자식과
  * `litellm-budget --refresh` 명령만 호출합니다.
  * /key/info(키·소속 식별)와 /user/info(팀 멤버십 예산)를 함께 조회합니다.
+ *
+ * `key` 를 넘기면 resolveKey() 를 다시 부르지 않고 그 값을 그대로 씁니다.
+ * 호출자(bin/cli.js 의 --refresh 분기)가 apiKeyHelper 를 한 번만 불러 이
+ * 함수와 게이트웨이 모델맵 갱신 양쪽에 같은 키를 재사용할 수 있도록 하는
+ * 목적입니다. 어느 경로든 키는 이 함수의 상태 파일에 기록되지 않습니다.
  */
-export async function refreshBudgetState(env = process.env, fetchImpl = fetch) {
+export async function refreshBudgetState(env = process.env, fetchImpl = fetch, key = null) {
   const base = gatewayBase(env);
   if (!base) return null;
-  const key = resolveKey(env);
-  if (!key) return null;
+  const resolvedKey = key || resolveKey(env);
+  if (!resolvedKey) return null;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   const headers = {
     accept: 'application/json',
-    authorization: `Bearer ${key}`,
+    authorization: `Bearer ${resolvedKey}`,
   };
   try {
     // /key/info 는 커스텀 인증(JWT)을 쓰는 배포에서 404 가 정상입니다. 발급된

package/src/litellm-models.js

@@ -0,0 +1,264 @@
+/**
+ * litellm-models: LiteLLM 게이트웨이의 `/model/info` 로부터 프로파일 ID → 모델
+ * 계열 매핑을 가져와 profile-map.json의 gateway 절에 캐시합니다.
+ *
+ * 왜 이 모듈이 필요한가: model-alias.js는 트랜스크립트의 서브에이전트 실행
+ * 기록을 모아 프로파일 ID의 역할(main/opus/sonnet/haiku)을 투표로 추정합니다.
+ * 이 학습 경로는 조건이 까다로워서(explicit 3표 이상·80% 동의) 대부분의
+ * 사용자에게서 매핑이 비어 있거나 늦게 채워집니다. 반면 LiteLLM
+ * `GET /model/info`는 배포마다 litellm_params.model(ARN)과 model_name(계열이
+ * 드러나는 이름)을 함께 돌려주므로, 게이트웨이가 이미 알고 있는 매핑을 굳이
+ * 투표로 다시 추론할 필요가 없습니다. 이 모듈은 그 지름길을 구현합니다.
+ *
+ * 왜 키를 인자로만 받는가: apiKeyHelper가 토큰의 수명(TTL)을 소유합니다. 이
+ * 모듈이 키를 파일이나 모듈 전역에 사본으로 두면 그 수명과 어긋나게 되므로,
+ * 사용자 지시에 따라 이 파일은 resolveKey()를 호출하지 않고 항상 key 인자로
+ * 전달받은 값만 요청 헤더에 씁니다. 키는 저장 객체·로그·에러 메시지 어디에도
+ * 남기지 않습니다.
+ *
+ * 왜 렌더 경로가 이 모듈을 기다리지 않는가: litellm-budget.js와 같은 모양으로,
+ * 네트워크 호출(refreshGatewayModelMap)은 갱신 경로(사람이 직접 실행하는
+ * `sprag profile-map --refresh`, 또는 litellm-budget 갱신에 편승하는
+ * maybeRefreshGatewayModelMap)에서만 일어납니다. statusline 렌더는
+ * readGatewayModelMap로 캐시 파일만 읽으므로 이 모듈이 fetch를 하는 동안
+ * 멈추는 일이 없습니다.
+ */
+
+import { gatewayBase } from './gateway-auth.js';
+import { loadProfileMap, updateProfileMap, resetModelAliasCache, profileIdFrom, isGatewayModelId } from './model-alias.js';
+import { isRecognizedModelId } from './cost.js';
+import { debug } from './debug.js';
+
+/** 게이트웨이 모델 맵의 신선도 기준. 배포 구성은 하루에 여러 번 바뀌지 않습니다. */
+export const MODEL_MAP_TTL_MS = 24 * 60 * 60 * 1000;
+
+const FETCH_TIMEOUT_MS = 5000;
+
+// litellm_params.model / model_info.base_model 앞에 붙는 공급자 접두어.
+// `bedrock/converse/`가 `bedrock/`의 접두어이기도 하므로, 긴 쪽을 먼저 검사해야
+// `converse/`가 그대로 남는 일이 없습니다.
+const PROVIDER_PREFIXES = ['bedrock/converse/', 'bedrock/', 'openai/', 'vertex_ai/', 'anthropic/'];
+
+/**
+ * 후보 문자열에서 공급자 접두어와 끝의 대괄호 접미어를 뗍니다.
+ *
+ * 접미어를 떼는 이유: 트랜스크립트는 컨텍스트 창 표시를 위해
+ * `ap-northeast-2.anthropic.claude-opus-5[1m]` 형태로 모델을 기록하지만,
+ * `/model/info`가 돌려주는 model_name/litellm_params.model에는 그 접미어가
+ * 없습니다. 접미어를 떼지 않으면 같은 모델을 가리키는 두 문자열이 서로 다른
+ * 키로 취급되어 별칭 판정이 실패합니다.
+ *
+ * ARN을 리소스 부분으로 줄이는 이유: ARN 문자열에는 12자리 AWS 계정 ID가 들어
+ * 있어서, 그것을 그대로 키나 별칭 값으로 쓰면 계정 ID가 profile-map.json에
+ * 기록됩니다. 리소스 부분만 남기면 `foundation-model` ARN은 계열명
+ * (`anthropic.claude-opus-5`)으로 줄어 별칭 값으로 쓸 수 있게 되고,
+ * `application-inference-profile` ARN은 불투명한 프로파일 ID로 줄어
+ * isRecognizedModelId()를 통과하지 못하므로 값이 아니라 키로만 쓰입니다.
+ * 줄이지 않으면 isRecognizedModelId()가 계열명을 품은 ARN 전체를 "인식됨"으로
+ * 판정해(cost.js의 정규식 한 줄이므로) 계정 ID가 값 쪽으로도 새어 나갑니다.
+ */
+function normalizeCandidate(id) {
+  if (typeof id !== 'string' || !id) return '';
+  let s = id;
+  if (isGatewayModelId(s)) return profileIdFrom(s) || '';
+  for (const prefix of PROVIDER_PREFIXES) {
+    if (s.startsWith(prefix)) {
+      s = s.slice(prefix.length);
+      break;
+    }
+  }
+  return s.replace(/\[[^\]]*\]$/, '');
+}
+
+/**
+ * `/model/info` 응답에서 프로파일 ID(또는 계열명 없는 사내 별칭) → 모델 계열
+ * 매핑을 뽑아냅니다. 순수 함수입니다: 네트워크·파일 I/O가 없고, 잘못된 입력에도
+ * 던지지 않습니다.
+ *
+ * 항목마다 별칭 후보를 model_name → model_info.base_model →
+ * litellm_params.model 순으로 검사해, 정규화 후 isRecognizedModelId()를
+ * 통과하는 첫 후보를 그 항목의 별칭으로 채택합니다. 세 후보 모두 인식하지
+ * 못하면 아무것도 기록하지 않고 model_name을 skipped에 넣습니다. 추측으로
+ * 잘못된 가격표를 매다는 것이 미해석 상태로 남기는 것보다 나쁩니다.
+ *
+ * 채택된 별칭에 대해 최대 두 개의 키를 기록합니다: (a) litellm_params.model이
+ * ARN이면 그 프로파일 ID, (b) model_name 자체가 별칭과 다르면(계열명이 없는
+ * 사내 별칭 사례) 정규화한 model_name. 이미 있는 키는 덮어쓰지 않습니다.
+ * 같은 프로파일 ID를 여러 배포 항목이 가리키면 첫 항목이 우선합니다.
+ *
+ * @param {unknown} payload `/model/info` 응답 본문
+ * @returns {{aliases: Record<string,string>, skipped: string[], count: number}}
+ */
+export function deriveAliasesFromModelInfo(payload) {
+  const data = Array.isArray(payload?.data) ? payload.data : null;
+  if (!data) return { aliases: {}, skipped: [], count: 0 };
+
+  const aliases = {};
+  const skipped = [];
+
+  for (const item of data) {
+    if (!item || typeof item !== 'object') continue;
+    const modelName = typeof item.model_name === 'string' ? item.model_name : '';
+    const baseModel = typeof item.model_info?.base_model === 'string' ? item.model_info.base_model : '';
+    const rawModel = typeof item.litellm_params?.model === 'string' ? item.litellm_params.model : '';
+
+    let alias = null;
+    for (const candidate of [modelName, baseModel, rawModel]) {
+      const normalized = normalizeCandidate(candidate);
+      if (normalized && isRecognizedModelId(normalized)) {
+        alias = normalized;
+        break;
+      }
+    }
+
+    if (!alias) {
+      if (modelName) skipped.push(modelName);
+      continue;
+    }
+
+    // (a) ARN 프로파일 ID. profileIdFrom은 원문(정규화 전) 문자열에서 뽑아야
+    // 합니다. 정규화는 공급자 접두어를 떼지만 ARN 본문은 그대로 두므로 원문을
+    // 넘겨도 동작하지만, 다른 후보에서 뽑은 alias와 혼동하지 않도록 항상
+    // litellm_params.model 원문을 씁니다.
+    const pid = profileIdFrom(rawModel);
+    if (pid && !(pid in aliases)) aliases[pid] = alias;
+
+    // (b) 계열명이 없는 사내 별칭(model_name). 이미 별칭 자체로 채택된
+    // 경우(정규화한 model_name === alias)는 중복이므로 기록하지 않습니다.
+    const normalizedName = normalizeCandidate(modelName);
+    if (normalizedName && normalizedName !== alias && !(normalizedName in aliases)) {
+      aliases[normalizedName] = alias;
+    }
+  }
+
+  return { aliases, skipped, count: data.length };
+}
+
+/**
+ * profile-map.json의 gateway 절을 읽습니다. base가 현재 gatewayBase(env)와
+ * 다르면 다른 게이트웨이의 캐시이므로 null을 돌려줍니다. 예산 캐시(budgetWindow)
+ * 와 같은 방식으로 게이트웨이 주소 단위로 격리합니다.
+ *
+ * @returns {{base:string, fetchedAt:string, aliases:Record<string,string>,
+ *            skipped:string[], count:number}|null}
+ */
+export function readGatewayModelMap(env = process.env) {
+  const base = gatewayBase(env);
+  if (!base) return null;
+  const gateway = loadProfileMap()?.gateway;
+  if (!gateway || typeof gateway !== 'object' || gateway.base !== base) return null;
+  return gateway;
+}
+
+/** base와 신선도(TTL) 기준으로 gateway 절이 오래됐는지 판정합니다 (내부 공용). */
+function isStaleFor(gateway, base, now) {
+  if (!base) return true;
+  if (!gateway || typeof gateway !== 'object' || gateway.base !== base) return true;
+  const fetchedAt = Date.parse(gateway.fetchedAt);
+  if (!Number.isFinite(fetchedAt)) return true;
+  return now - fetchedAt > MODEL_MAP_TTL_MS;
+}
+
+/**
+ * gateway 절이 없거나, 다른 게이트웨이 것이거나, fetchedAt이 MODEL_MAP_TTL_MS
+ * 보다 오래됐으면 true.
+ */
+export function isGatewayModelMapStale(env = process.env, now = Date.now()) {
+  const base = gatewayBase(env);
+  return isStaleFor(loadProfileMap()?.gateway, base, now);
+}
+
+/**
+ * LiteLLM `GET {base}/model/info`를 호출해 gateway 절을 갱신합니다.
+ *
+ * key는 호출자가 이미 확보해 둔 값을 그대로 받습니다. 이 함수는 resolveKey()를
+ * 부르지 않고, key가 없으면 즉시 null을 돌려줍니다(헬퍼를 다시 부르지 않도록
+ * 하기 위함이며, 헬퍼가 Okta 로그인을 띄우는 배포에서 이 함수가 조용히 그
+ * 팝업을 다시 띄우는 일이 없어야 합니다).
+ *
+ * 실패(비 200·타임아웃·파싱 실패)는 예외를 던지지 않고 debug()로만 남기며,
+ * 이 경우 profile-map.json을 건드리지 않습니다. 부분 실패로 기존 gateway
+ * 절을 지우면 다음 렌더가 이미 알던 매핑까지 잃습니다.
+ *
+ * @returns {Promise<{aliases:Record<string,string>, skipped:string[], count:number}|null>}
+ */
+export async function refreshGatewayModelMap({ base, key, fetchImpl = fetch } = {}) {
+  if (!base || !key) return null;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    let res;
+    try {
+      res = await fetchImpl(`${base}/model/info`, {
+        signal: controller.signal,
+        headers: { accept: 'application/json', authorization: `Bearer ${key}` },
+      });
+    } catch (e) {
+      debug('litellm-models:fetch', e);
+      return null;
+    }
+    if (!res.ok) {
+      debug('litellm-models:fetch', new Error(`LiteLLM responded ${res.status}`));
+      return null;
+    }
+    let payload;
+    try {
+      // 응답 본문을 debug로 덤프하지 않습니다. 마스킹되지 않은 필드가 섞여
+      // 있을 가능성을 배제할 수 없고, 파싱 실패 로그는 예외 메시지만으로 충분합니다.
+      payload = await res.json();
+    } catch (e) {
+      debug('litellm-models:parse', e);
+      return null;
+    }
+
+    const result = deriveAliasesFromModelInfo(payload);
+    // 200 응답이라도 본문 형태가 다르면 실패로 취급합니다. deriveAliases…는
+    // data가 배열이 아니면 빈 결과를 돌려주는데, 그 빈 결과를 그대로 기록하면
+    // 잘 채워져 있던 캐시가 지워집니다. 형태 불일치는 게이트웨이 구성이 바뀐
+    // 신호이거나 다른 서비스의 응답이므로, 옛 답을 남겨 두는 편이 안전합니다.
+    if (!Array.isArray(payload?.data)) {
+      debug('litellm-models:shape', new Error('response has no data array'));
+      return null;
+    }
+    // 이 판정은 디스크의 현재 상태를 봐야 하므로 메모이즈된 값을 쓰지 않습니다.
+    resetModelAliasCache();
+    const map = loadProfileMap();
+    // 별칭을 하나도 못 뽑았는데 기존 맵에는 있었다면 덮어쓰지 않습니다. 키가
+    // 사라지는 쪽이 오래된 키를 남겨 두는 쪽보다 나쁘고(해석이 통째로 unknown이
+    // 됩니다), 이 상태는 대개 일시적인 구성 오류입니다.
+    const had = map.gateway?.base === base ? Object.keys(map.gateway.aliases || {}).length : 0;
+    if (Object.keys(result.aliases).length === 0 && had > 0) {
+      debug('litellm-models:empty', new Error(`derived 0 aliases, keeping ${had} cached`));
+      return null;
+    }
+    // gateway 절만 갱신합니다. updateProfileMap이 쓰기 직전에 파일을 다시 읽어
+    // 병합하므로, 이 네트워크 호출이 오가는 동안 route-scan의 학습 경로가
+    // learned를 기록했더라도 그 결과를 지우지 않습니다. 반대 방향도 같습니다.
+    updateProfileMap({
+      gateway: {
+        base,
+        fetchedAt: new Date().toISOString(),
+        aliases: result.aliases,
+        skipped: result.skipped,
+        count: result.count,
+      },
+    });
+    return result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * gateway 절이 stale할 때만 refreshGatewayModelMap을 호출합니다. base/key가
+ * 없으면 호출 없이 null.
+ *
+ * litellm-budget의 --refresh 경로가 이미 얻어 둔 key를 재사용해 이 함수를
+ * 호출하므로, apiKeyHelper는 그 갱신 경로 안에서 한 번만 실행됩니다.
+ */
+export async function maybeRefreshGatewayModelMap({ base, key, fetchImpl = fetch, now = Date.now() } = {}) {
+  if (!base || !key) return null;
+  if (!isStaleFor(loadProfileMap()?.gateway, base, now)) return null;
+  return refreshGatewayModelMap({ base, key, fetchImpl });
+}

package/src/model-alias.js

@@ -18,22 +18,30 @@
  * all that is missing is ARN → alias.
  *
  * Resolution order, cheapest first:
- *   1. not an ARN            → return the input unchanged (direct-API users
+ *   1. user override         → `modelAliases` in profile-map.json
+ *   2. gateway declaration   → `gateway.aliases` in profile-map.json, fetched
+ *                              from the LiteLLM gateway's own /model/info;
+ *                              consulted ahead of learned votes because it is
+ *                              the gateway's own declared mapping, not an
+ *                              inference drawn from transcripts
+ *   3. not an ARN            → return the input unchanged (direct-API users
  *                              must keep their existing behaviour)
- *   2. user override         → `modelAliases` in profile-map.json
- *   3. learned mapping       → profile id → role, learned from transcripts
- *   4. otherwise             → 'unknown' (never a silent Sonnet guess)
+ *   4. self-describing id    → a profile id that already spells out a family
+ *                              (`foundation-model` ARNs, cross-region ids)
+ *   5. learned mapping       → profile id → role, learned from transcripts
+ *   6. otherwise             → 'unknown' (never a silent Sonnet guess)
  *
  * A profile id is never hardcoded here. Ids differ per account and change
  * with gateway config, and the ARN embeds a 12-digit AWS account id — this
  * package is published to npm, so neither may live in the source.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, createReadStream } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, createReadStream, statSync, renameSync } from 'node:fs';
 import { readFile, readdir } from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 import { join, dirname, basename } from 'node:path';
 import { userDataDir, claudeUserDir } from './paths.js';
+import { gatewayBase } from './gateway-auth.js';
 
 /** Marker returned when a gateway id could not be resolved to a model. */
 export const UNKNOWN_MODEL = 'unknown';
@@ -109,9 +117,19 @@ export function loadProfileMap() {
   try {
     data = JSON.parse(readFileSync(profileMapPath(), 'utf8'));
   } catch { /* absent on first run, and unreadable is not fatal */ }
+  // `gateway` is written by `sprag profile-map --refresh` (src/litellm-models.js),
+  // never by this module. Shape it defensively: a half-written or
+  // hand-edited file must fall back to "no gateway data" rather than throw
+  // or feed garbage into gatewayAlias() below.
+  const gw = data.gateway;
+  const gateway = (gw && typeof gw === 'object'
+    && typeof gw.base === 'string' && gw.aliases && typeof gw.aliases === 'object')
+    ? { ...gw, skipped: Array.isArray(gw.skipped) ? gw.skipped : [] }
+    : null;
   cached = {
     version: 1,
     modelAliases: data.modelAliases && typeof data.modelAliases === 'object' ? data.modelAliases : {},
+    gateway,
     learned: data.learned && typeof data.learned === 'object' ? data.learned : {},
     learnedAt: data.learnedAt || null,
     scannedSessions: data.scannedSessions || 0,
@@ -120,10 +138,53 @@ export function loadProfileMap() {
 }
 
 export function saveProfileMap(map) {
+  writeProfileMapFile(map);
+  cached = map;
+}
+
+/**
+ * Write the file so a reader never sees a half-written one: serialize to a
+ * sibling temp path, then rename, which is atomic within a directory. The old
+ * in-place `writeFileSync` could be interrupted mid-write, and `loadProfileMap`
+ * treats a corrupt file as an empty map — so a crash at the wrong moment
+ * silently discarded the user's hand-written `modelAliases`.
+ */
+function writeProfileMapFile(map) {
   const dir = userDataDir();
   mkdirSync(dir, { recursive: true });
-  writeFileSync(profileMapPath(), JSON.stringify(map, null, 2));
-  cached = map;
+  const target = profileMapPath();
+  const tmp = `${target}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(map, null, 2));
+  renameSync(tmp, target);
+}
+
+/**
+ * Merge `patch`'s top-level keys into whatever is on disk RIGHT NOW, then
+ * write.
+ *
+ * Two producers update this file from separate detached processes, and each
+ * owns different keys: route-scan's learner writes `learned`/`learnedAt`/
+ * `scannedSessions`, and the gateway refresh writes `gateway`. Both used to
+ * spread a snapshot taken when their process started (`{...loadProfileMap()}`)
+ * and write the whole document back, so whichever finished last erased the
+ * other's section. A scan takes about half a second and the gateway refresh
+ * makes a network call inside the same window, so the overlap was not
+ * theoretical — and the damage is silent: resolution simply falls back to
+ * 'unknown' with nothing in any log to say why.
+ *
+ * Re-reading immediately before the rename narrows the window from the length
+ * of the whole operation to the few microseconds between read and rename. That
+ * is not a lock, and a true one would need an O_EXCL lockfile plus stale-lock
+ * recovery; the remaining race can only lose a section that was written inside
+ * those microseconds, and the next refresh restores it.
+ */
+export function updateProfileMap(patch) {
+  cached = null;
+  const fresh = loadProfileMap();
+  const next = { ...fresh, ...patch };
+  writeProfileMapFile(next);
+  cached = next;
+  return next;
 }
 
 /** Drop the memoized map. Tests use this after pointing paths elsewhere. */
@@ -154,6 +215,58 @@ function overrideAlias(model, map) {
   return null;
 }
 
+/**
+ * Alias declared by the gateway itself (LiteLLM's `/model/info`, cached
+ * under `gateway` in profile-map.json) rather than inferred from transcript
+ * votes. Consulted ahead of the learned-vote path for exactly that reason:
+ * this is the gateway telling us its own configuration, not a guess built
+ * from run counts.
+ *
+ * Isolated per gateway address the same way the budget cache is (see
+ * litellm-budget.js) — a table fetched from one `ANTHROPIC_BASE_URL` must
+ * never answer for a different one, so a base mismatch is treated the same
+ * as no gateway data at all.
+ *
+ * Looked up three ways, because the string this function receives is not
+ * always the string `/model/info` reported: transcripts append a `[1m]`
+ * context-window suffix that the gateway's response never carries, and the
+ * input here is sometimes a full ARN where `/model/info` only ever named
+ * the bare profile id. Fails quiet throughout — any shape mismatch (no
+ * gateway section, a different base, no matching key) returns null and the
+ * caller falls through to the resolution steps that existed before this one.
+ *
+ * Freshness matters as much as the base. This step outranks learned votes
+ * because the gateway DECLARES the mapping rather than inferring it, and that
+ * argument only holds while the declaration is current. A machine whose
+ * refresh has been failing for weeks (permissions revoked, `/model/info` now
+ * 403, the proxy moved) would otherwise let a months-old table outrank
+ * thousands of accumulating votes forever, which is the opposite of what the
+ * ordering was chosen for. Past the grace window the table steps aside and
+ * learning answers again; it is not deleted, because the next successful
+ * refresh should be able to reuse the file, and `sprag profile-map` still
+ * shows it with its age.
+ */
+const MODEL_MAP_GRACE_MS = 14 * 24 * 60 * 60 * 1000;
+
+function gatewayAlias(model, map, env, now = Date.now()) {
+  const gw = map.gateway;
+  if (!gw || !gw.aliases || gw.base !== gatewayBase(env)) return null;
+  const fetchedAt = Date.parse(gw.fetchedAt);
+  if (!Number.isFinite(fetchedAt) || now - fetchedAt > MODEL_MAP_GRACE_MS) return null;
+  const bare = model.replace(/\[[^\]]*\]$/, '');
+  const pid = profileIdFrom(model);
+  // `hasOwn` rather than a bare index: this object comes from JSON.parse, so
+  // it carries Object.prototype, and a transcript model id of 'constructor'
+  // or 'toString' would otherwise resolve to a function.
+  for (const key of [model, bare, pid]) {
+    if (key && Object.hasOwn(gw.aliases, key)) {
+      const alias = gw.aliases[key];
+      if (typeof alias === 'string' && alias) return alias;
+    }
+  }
+  return null;
+}
+
 // ── resolution ───────────────────────────────────────────────────────────
 
 /**
@@ -176,6 +289,13 @@ export function resolveModelAlias(rawModel, { env = process.env } = {}) {
   const override = overrideAlias(model, map);
   if (override) return override;
 
+  // The gateway's own declared mapping runs next, and — like the override
+  // above — for every id, not just ARNs. A house alias with no family name
+  // (`prod-large`) is never an ARN, so it would otherwise fall straight
+  // through the isGatewayModelId check below to a silent Sonnet default.
+  const gatewayHit = gatewayAlias(model, map, env);
+  if (gatewayHit) return gatewayHit;
+
   if (!isGatewayModelId(model)) return model;
 
   const pid = profileIdFrom(model);
@@ -423,6 +543,37 @@ export function tallyVotes(votes, { minVotes = MIN_VOTES, minAgreement = MIN_AGR
   return learned;
 }
 
+/**
+ * Sort transcript paths newest-first, so the `maxSessions` truncation in
+ * learnProfileMapping keeps the most RECENT sessions.
+ *
+ * This used to be a caller contract ("newest first" in the JSDoc), and the
+ * only caller broke it: `runRouteScan` hands over `discoverSessionFiles()`
+ * output, which parser.js sorts OLDEST first because chronological order is
+ * what parsing wants. Learning then read the oldest `maxSessions` files and
+ * never saw recent delegations, so a profile that only appears in the last few
+ * days stayed unresolved and every run on it dropped out of the aggregate.
+ * Measured on one 14-day window: 95 transcripts, of which learning read
+ * 09-04 through 09-15 and discarded the three most recent days — including the
+ * sessions holding the haiku evidence it needed.
+ *
+ * Sorting here rather than at the call site puts the invariant in the same
+ * function as the truncation that depends on it, so a future caller cannot
+ * reintroduce the bug. Cost is one stat() per candidate path, against a scan
+ * that already stats every file to build the window.
+ */
+function newestFirst(paths) {
+  return paths
+    .map((p) => {
+      let mtime = 0;
+      // An unreadable path sorts last and then fails harmlessly in the loop.
+      try { mtime = statSync(p).mtimeMs; } catch { /* keep 0 */ }
+      return { p, mtime };
+    })
+    .sort((a, b) => b.mtime - a.mtime)
+    .map((e) => e.p);
+}
+
 /**
  * Learn profile id → role from transcripts and persist the result.
  *
@@ -432,7 +583,8 @@ export function tallyVotes(votes, { minVotes = MIN_VOTES, minAgreement = MIN_AGR
  * id and the requested role identify each other.
  *
  * @param {object}   opts
- * @param {string[]} opts.sessionPaths transcripts to read, newest first
+ * @param {string[]} opts.sessionPaths transcripts to read, in any order — they
+ *                                     are sorted newest-first here, see below
  * @param {number}   opts.maxSessions  cap on files read (learning is a scan)
  * @returns {Promise<{learned: object, scannedSessions: number, gateway: boolean}>}
  */
@@ -442,7 +594,7 @@ export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40
   let scanned = 0;
   let gateway = false;
 
-  for (const sessionPath of sessionPaths.slice(0, maxSessions)) {
+  for (const sessionPath of newestFirst(sessionPaths).slice(0, maxSessions)) {
     const requestedByToolUse = new Map();
     let sawGateway = false;
     try {
@@ -472,13 +624,15 @@ export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40
 
   const learned = tallyVotes(votes);
   const map = loadProfileMap();
-  const next = {
-    ...map,
-    learned,
-    learnedAt: new Date().toISOString(),
-    scannedSessions: scanned,
-  };
   // Nothing to record on a non-gateway machine — do not create the file there.
-  if (gateway || Object.keys(map.learned || {}).length) saveProfileMap(next);
+  // Writes only this learner's own keys, so a gateway refresh that landed while
+  // this scan was running keeps its section (see updateProfileMap).
+  if (gateway || Object.keys(map.learned || {}).length) {
+    updateProfileMap({
+      learned,
+      learnedAt: new Date().toISOString(),
+      scannedSessions: scanned,
+    });
+  }
   return { learned, scannedSessions: scanned, gateway };
 }