claude-token-saver 3.9.1 → 3.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rootstudioyaml
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -17,6 +17,23 @@ npm i -g claude-token-saver   # postinstall auto-registers the statusline + Skil
 
 ![statusline example](./docs/statusline.png)
 
+## 📺 Came here from the video? — 60 seconds
+
+This is not a router. It never intercepts a request in realtime.
+**After a session ends** it reads your local logs, finds the easy patterns your expensive model
+kept handling, and promotes them into rules so a cheaper model takes them **from the next session
+onward**. Rules are scoped global or per-project.
+
+```bash
+npm i -g claude-token-saver@latest
+claude-token-saver route-scan         # find delegation candidates in your own history (0 LLM calls)
+claude-token-saver route-scan rules   # list promoted rules · rm <N> to remove
+```
+
+Thresholds come from **your own last-14-day distribution (p25/p75)**, not someone else's benchmark.
+Measured rule-health — whether a delegated run actually succeeded — landed in [v3.9.0](#v390-2026-08-01).
+
+
 ## ⚡ Why — the 30-second pitch
 
 | | |
@@ -185,6 +202,24 @@ claude-token-saver route-scan rules              # list model-fitting rules (rm
 
 Dig deeper: **tier criteria & research evidence** → [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) (Korean) · **rule-file mechanics, scan triggers, subagent setup** → [docs/ROUTE_SCAN.md](./docs/ROUTE_SCAN.md) (Korean + English)
 
+### Behind a gateway (Bedrock / LiteLLM)
+
+Through a corporate gateway the transcript records an inference-profile ARN where the model id belongs. That string says nothing about `opus` or `haiku`, so older versions read every session as Sonnet — which made **T1 (→sonnet) rules unreachable and zeroed the savings figures**.
+
+Since v3.10.0 the profile id is mapped back to a role (main, opus, sonnet, haiku) and then to the alias your `ANTHROPIC_DEFAULT_*_MODEL` variables declare. The mapping is learned by joining each parent `Task` call to the subagent run it spawned via `toolUseId`. Below three observations, or when the role votes agree less than 80% of the time, the id stays `unknown` and drops out of the delegation aggregate rather than being guessed at.
+
+For environments the learner cannot reach, write the mapping yourself in `<userDataDir>/profile-map.json`. Account id and region may be wildcarded:
+
+```jsonc
+{
+  "modelAliases": {
+    "arn:aws:bedrock:*:*:application-inference-profile/<PROFILE_ID>": "claude-opus-5"
+  }
+}
+```
+
+That file holds internal identifiers in plain text — do not commit it. On a direct-API machine it is never created and behaviour is unchanged.
+
 ## Spike issue codes
 
 | Code | Meaning |
@@ -265,6 +300,18 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.10.0 (2026-08-20)
+- **Model tiers are detected again behind a Bedrock / LiteLLM gateway** — when the transcript's model id is an inference-profile ARN there is no `opus` or `haiku` in the string, so it fell back to Sonnet. Since `worthDelegating()` requires `rank > target`, **every T1 rule was rejected**, savings aggregated to zero, and cost was under-counted by roughly 1.67x. The profile id is now learned as a role (parent `Task` call joined to the subagent run by `toolUseId`) and mapped back to the alias your environment declares. The pricing table, the ranks, and the tiering logic are untouched.
+- **No confident mapping means no guess** — under three observations, or below 80% agreement, the id stays `unknown` and leaves the delegation aggregate. Quietly calling it Sonnet was the worse failure.
+- **Manual override** — `modelAliases` in `<userDataDir>/profile-map.json`, wildcards allowed. No profile id or AWS account id is ever hardcoded in this package.
+- Direct-API machines behave **exactly as before** and no new file is written.
+
+### v3.9.2 (2026-08-01)
+- **Added a LICENSE file (MIT)** — the field existed in `package.json` but the file did not, which blocked license review for company adoption. It ships in the npm tarball now via `files`.
+- **Package description and keywords rewritten for what this actually does** — leftover cache-monitoring copy meant it never surfaced for `model-routing` / `delegation` / `subagent`.
+- **A 60-second on-ramp at the top of the README** — that this is post-hoc analysis rather than a router, plus the three commands from install to seeing your own numbers.
+- **One-time note in `route-scan`** — prints the explainer link exactly once. Disable with `CTS_NO_NOTE=1`.
+
 ### v3.9.1 (2026-08-01)
 - **compact-window now recommends a 400k–700k band instead of a single 400k** — 400k proved too tight in practice and compacted too often. The advice is a range now, and **a window inside it (or below it) is never warned about**; only an unset value or one above 700k raises `🅷⚠ compact-window?` and the briefing. `set` defaults to 500k (mid-band); pick your own with `--value 600k`.
 

package/README.md

@@ -17,6 +17,22 @@ npm i -g claude-token-saver   # postinstall이 statusline + Skill 자동 등록
 
 ![statusline 예시](./docs/statusline.png)
 
+## 📺 영상 보고 오셨다면 — 60초
+
+라우터가 아닙니다. 요청을 실시간으로 가로채지 않습니다.
+**세션이 끝난 뒤** 로컬 기록을 읽어서, 비싼 모델이 반복해서 처리해 온 쉬운 유형을 뽑고,
+그 유형은 **다음 세션부터** 싼 모델이 맡도록 룰로 겁니다. 룰은 글로벌·프로젝트로 범위가 나뉩니다.
+
+```bash
+npm i -g claude-token-saver@latest
+claude-token-saver route-scan         # 내 지난 세션에서 위임 후보 뽑기 (LLM 호출 0)
+claude-token-saver route-scan rules   # 승격된 룰 확인 · rm <N> 으로 삭제
+```
+
+기준선은 남의 벤치마크가 아니라 **내 최근 14일 분포(p25/p75)** 로 잡습니다.
+넘긴 뒤 실제로 잘 됐는지까지 재는 실측 rule-health는 [v3.9.0](#v390-2026-08-01)에 들어갔습니다.
+
+
 ## ⚡ 왜 쓰나 — 30초 요약
 
 | | |
@@ -166,6 +182,24 @@ claude-token-saver route-scan rules              # 등록된 모델 피팅 룰
 
 더 알아보기: **티어 기준·리서치 근거** → [docs/TIER_CRITERIA.md](./docs/TIER_CRITERIA.md) · **룰 파일 구조·스캔 트리거·서브에이전트 준비** → [docs/ROUTE_SCAN.md](./docs/ROUTE_SCAN.md)
 
+### 게이트웨이(Bedrock·LiteLLM) 경유 환경
+
+사내 게이트웨이를 거치면 로그의 모델명 자리에 추론 프로파일 ARN이 기록됩니다. 그 문자열에는 `opus`·`haiku` 같은 단서가 없어서 예전 버전은 이것을 전부 Sonnet으로 읽었고, 그 결과 **T1(→sonnet) 위임 룰이 하나도 제안되지 않았으며 절감 집계가 0**이었습니다.
+
+v3.10.0부터는 프로파일 ID를 역할(main·opus·sonnet·haiku)로 되돌린 뒤 `ANTHROPIC_DEFAULT_*_MODEL` 환경변수가 선언한 별칭으로 치환합니다. 매핑은 부모 세션의 `Task` 호출과 서브에이전트 기록을 `toolUseId`로 조인해 스스로 학습하며, 관측이 3건 미만이거나 역할 판정이 80% 미만으로 갈리면 **추측하지 않고 `unknown`으로 두고 위임 집계에서 제외**합니다.
+
+자동 학습이 닿지 않는 환경을 위한 수동 경로도 있습니다. `<userDataDir>/profile-map.json`에 아래처럼 적으면 되고, 계정 ID와 리전은 `*`로 가려도 매칭됩니다.
+
+```jsonc
+{
+  "modelAliases": {
+    "arn:aws:bedrock:*:*:application-inference-profile/<PROFILE_ID>": "claude-opus-5"
+  }
+}
+```
+
+이 파일에는 사내 식별자가 평문으로 남으므로 저장소에 커밋하지 마십시오. 게이트웨이를 쓰지 않는 환경에서는 파일이 아예 만들어지지 않고 기존 동작이 그대로 유지됩니다.
+
 ## 토큰 급증 원인 코드
 
 | 코드 | 의미 |
@@ -222,6 +256,18 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.10.0 (2026-08-20)
+- **게이트웨이(Bedrock·LiteLLM) 환경에서 모델 티어를 다시 인식합니다** — 로그의 모델명이 추론 프로파일 ARN이면 `opus`·`haiku` 단서가 없어 Sonnet으로 폴백했고, `worthDelegating()`이 `rank > target`을 요구하므로 **T1 위임이 전부 기각**됐습니다. 절감 집계는 0, 비용은 약 1.67배 과소 계상이었습니다. 이제 프로파일 ID를 역할로 학습해(부모 `Task` 호출 ↔ 서브에이전트 `toolUseId` 정확 조인) 환경변수가 선언한 별칭으로 되돌립니다. 가격표·랭크·판정 로직은 그대로입니다.
+- **확신이 없으면 숨기지 않고 드러냅니다** — 관측 3건 미만이거나 역할 동의율 80% 미만이면 `unknown`으로 두고 위임 집계에서 제외합니다. Sonnet으로 조용히 틀리던 기존 동작이 더 나빴습니다.
+- **수동 오버라이드** — `<userDataDir>/profile-map.json`의 `modelAliases`에 와일드카드 패턴으로 직접 지정할 수 있습니다. 프로파일 ID·AWS 계정 ID는 소스에 전혀 넣지 않습니다.
+- 게이트웨이를 쓰지 않는 환경은 **동작이 완전히 동일**합니다(파일도 만들지 않습니다).
+
+### v3.9.2 (2026-08-01)
+- **LICENSE 파일 추가 (MIT)** — `package.json`에만 있고 파일이 없어서, 사내 도입 검토 시 라이선스 확인이 막히던 문제. npm 패키지에도 포함되도록 `files`에 넣었습니다.
+- **패키지 설명·키워드를 현재 기능에 맞게 교체** — 캐시 모니터링 시절 문구가 남아 있어 모델 위임(`model-routing`·`delegation`·`subagent`)으로 검색되지 않았습니다.
+- **README 상단에 60초 진입로** — 라우터가 아니라 사후 분석이라는 점과, 설치부터 내 숫자 확인까지의 명령 3줄.
+- **`route-scan` 최초 1회 안내** — 기능 설명 영상 링크를 딱 한 번만 출력합니다. `CTS_NO_NOTE=1`로 끕니다.
+
 ### v3.9.1 (2026-08-01)
 - **compact-window 권장값이 단일 40만에서 40만~70만 범위로** — 40만은 실사용에서 너무 빡빡해 압축이 잦았습니다. 이제 범위를 제안하고, **그 안(또는 그보다 낮게) 잡아둔 세션은 경고하지 않습니다.** 미설정이거나 70만 초과일 때만 `🅷⚠ compact-window?`와 브리핑이 뜹니다. `set`의 기본값도 범위 중간인 50만으로 올렸고, 원하는 값은 `--value 600k`로 지정합니다.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-token-saver",
-  "version": "3.9.1",
-  "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
+  "version": "3.10.0",
+  "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {
     "claude-token-saver": "bin/cli.js"
@@ -16,22 +16,27 @@
     "presets/",
     "examples/",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"
   },
   "keywords": [
     "claude",
+    "claude-code",
     "anthropic",
-    "cache",
-    "monitoring",
+    "model-routing",
+    "llm-router",
+    "delegation",
+    "subagent",
+    "haiku",
+    "cost-savings",
+    "token-usage",
     "prompt-caching",
-    "cli",
+    "cache",
     "statusline",
-    "claude-code",
-    "token-usage",
-    "cost-savings",
+    "cli",
     "1m-context"
   ],
   "license": "MIT",

package/src/commands/route-scan.js

@@ -202,6 +202,7 @@ export async function run({ args, hasFlag, numArg }) {
       console.log(lang === 'ko'
         ? '위임 후보 없음 (반복 3회 미만이거나 이미 처리됨).'
         : 'No delegation candidates (below recurrence threshold or already resolved).');
+      (await import('../first-run-note.js')).printOnce('route-scan', lang);
       return;
     }
     console.log(lang === 'ko' ? '\n위임 후보 (R<N>=후보 번호, T2/T1=난이도 등급):' : '\nDelegation candidates (R<N> = candidate id, T2/T1 = difficulty tier):');
@@ -223,5 +224,7 @@ export async function run({ args, hasFlag, numArg }) {
     console.log(lang === 'ko' ? '등록 / 무시:' : 'Promote / dismiss:');
     console.log('  claude-token-saver harness promote R<N> --project|--global');
     console.log('  claude-token-saver route-scan dismiss <N>');
+    // 최초 1회만 — 매번 찍으면 도구가 광고판이 된다 (CTS_NO_NOTE=1 로 끔)
+    (await import('../first-run-note.js')).printOnce('route-scan', lang);
     return;
 }

package/src/cost.js

@@ -117,7 +117,22 @@ const TIER_RANK = {
   'claude-haiku-3': 0,
 };
 
+/**
+ * True for the explicit 'unknown' marker — an id that could not be resolved
+ * at all (see model-alias.js), as opposed to an id this table simply has no
+ * entry for. The two must not share a fate: an unresolved gateway id counted
+ * as Sonnet silently corrupts every delegation statistic, so it is dropped
+ * from the ranking instead of guessed at.
+ */
+export function isUnknownModel(model) {
+  return !model || String(model).toLowerCase() === 'unknown';
+}
+
 export function modelRank(model) {
+  // -1 sits below every real tier, so worthDelegating() rejects it and
+  // tierForRank() attributes no saving to it: the run leaves the aggregate
+  // rather than distorting it.
+  if (isUnknownModel(model)) return -1;
   const rank = TIER_RANK[detectPricingTier(model)];
   // Unknown ids fall through detectPricingTier to the Sonnet tier; ranking
   // them 1 keeps the conservative reading (cheap enough that a Sonnet-target

package/src/first-run-note.js

@@ -0,0 +1,63 @@
+/**
+ * first-run-note — a one-time pointer to where a feature is explained.
+ *
+ * A CLI that advertises on every invocation stops being a tool, so this fires
+ * ONCE per note key and then never again: the shown-at timestamp is persisted
+ * next to the other state files and checked before anything is printed.
+ *
+ * Opt out entirely with CTS_NO_NOTE=1 (also honoured by anything that pipes
+ * our output somewhere it does not belong).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+export function firstRunStatePath() {
+  return join(userDataDir(), 'first-run.json');
+}
+
+function load() {
+  try {
+    const s = JSON.parse(readFileSync(firstRunStatePath(), 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {};
+  }
+}
+
+function markShown(key, now) {
+  const state = load();
+  state[key] = now;
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(firstRunStatePath(), JSON.stringify(state) + '\n');
+}
+
+/** True only the first time this key is asked about. Best-effort — a
+ *  read-only state dir just means the note repeats, never that we crash. */
+export function shouldShowOnce(key, { now = Date.now() } = {}) {
+  if (process.env.CTS_NO_NOTE === '1') return false;
+  if (load()[key]) return false;
+  try {
+    markShown(key, now);
+  } catch {
+    /* state dir unwritable — show it, do not fail the command */
+  }
+  return true;
+}
+
+const NOTES = {
+  'route-scan': {
+    ko: '📺 이 기능을 설명한 영상: https://www.youtube.com/@DeepPulseKR  (이 안내는 한 번만 표시됩니다)',
+    en: '📺 How this works, in 3 minutes: https://www.youtube.com/@DeepPulseEN  (shown once)',
+  },
+};
+
+/** Print the one-time note for `key`, or nothing. */
+export function printOnce(key, lang = 'en') {
+  const note = NOTES[key];
+  if (!note || !shouldShowOnce(key)) return;
+  console.log('');
+  console.log(lang === 'ko' ? note.ko : note.en);
+}

package/src/model-alias.js

@@ -0,0 +1,364 @@
+/**
+ * model-alias — restore a usable model name when the transcript records a
+ * gateway identifier instead of a Claude model id.
+ *
+ * Why this exists: behind a Bedrock / LiteLLM gateway, `message.model` in the
+ * transcript is an inference-profile ARN:
+ *
+ *   converse/arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>
+ *
+ * Nothing in that string says "opus" or "haiku", so `detectPricingTier()`
+ * falls through to its Sonnet default. Everything downstream then reads the
+ * session as Sonnet: `worthDelegating('T1', 1)` is false, so every T1 rule is
+ * rejected, delegation savings aggregate to zero, and cost is under-counted.
+ *
+ * The fix is a single normalization point rather than a change to the pricing
+ * table — plain aliases (`ap-northeast-2.anthropic.claude-opus-5[1m]`) are
+ * already classified correctly, region prefix and `[1m]` suffix included. So
+ * all that is missing is ARN → alias.
+ *
+ * Resolution order, cheapest first:
+ *   1. 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)
+ *
+ * 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 { readFile, readdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { join, dirname, basename } from 'node:path';
+import { userDataDir, claudeUserDir } from './paths.js';
+
+/** Marker returned when a gateway id could not be resolved to a model. */
+export const UNKNOWN_MODEL = 'unknown';
+
+/** File holding user overrides plus the learned profile→role votes. */
+export function profileMapPath() {
+  return join(userDataDir(), 'profile-map.json');
+}
+
+// `converse/` (LiteLLM) or a bare ARN, foundation- or application-scoped.
+const ARN_RE =
+  /arn:aws:bedrock:[^:]*:[^:]*:(?:application-)?inference-profile\/([A-Za-z0-9._:-]+)/;
+
+/** True when the id came from a Bedrock gateway rather than the Claude API. */
+export function isGatewayModelId(model) {
+  return typeof model === 'string' && model.includes('arn:aws:bedrock:');
+}
+
+/** The inference-profile id inside an ARN, or null when there is none. */
+export function profileIdFrom(model) {
+  if (typeof model !== 'string') return null;
+  const m = ARN_RE.exec(model);
+  return m ? m[1] : null;
+}
+
+/**
+ * Roles a profile id can carry. 'main' is the session's own model, which the
+ * env declares separately from the per-tier subagent overrides.
+ */
+const ROLES = ['main', 'opus', 'sonnet', 'haiku', 'fable'];
+
+/**
+ * Alias for a role, taken from the environment Claude Code itself uses to
+ * pick subagent models. Returns null when the variable is absent or is itself
+ * an ARN (resolving an ARN to another ARN would loop).
+ */
+export function aliasForRole(role, env = process.env) {
+  const candidates = {
+    main: [env.ANTHROPIC_MODEL, env.ANTHROPIC_DEFAULT_MODEL, env.ANTHROPIC_DEFAULT_OPUS_MODEL],
+    opus: [env.ANTHROPIC_DEFAULT_OPUS_MODEL, env.ANTHROPIC_MODEL],
+    sonnet: [env.ANTHROPIC_DEFAULT_SONNET_MODEL],
+    haiku: [env.ANTHROPIC_DEFAULT_HAIKU_MODEL],
+    fable: [env.ANTHROPIC_DEFAULT_FABLE_MODEL],
+  }[role] || [];
+  for (const v of candidates) {
+    if (typeof v === 'string' && v && !isGatewayModelId(v)) return v;
+  }
+  return null;
+}
+
+// ── override / learned map storage ───────────────────────────────────────
+
+let cached = null;
+
+/** Read profile-map.json (memoized). Missing or corrupt file → empty map. */
+export function loadProfileMap() {
+  if (cached) return cached;
+  let data = {};
+  try {
+    data = JSON.parse(readFileSync(profileMapPath(), 'utf8'));
+  } catch { /* absent on first run, and unreadable is not fatal */ }
+  cached = {
+    version: 1,
+    modelAliases: data.modelAliases && typeof data.modelAliases === 'object' ? data.modelAliases : {},
+    learned: data.learned && typeof data.learned === 'object' ? data.learned : {},
+    learnedAt: data.learnedAt || null,
+    scannedSessions: data.scannedSessions || 0,
+  };
+  return cached;
+}
+
+export function saveProfileMap(map) {
+  const dir = userDataDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(profileMapPath(), JSON.stringify(map, null, 2));
+  cached = map;
+}
+
+/** Drop the memoized map. Tests use this after pointing paths elsewhere. */
+export function resetModelAliasCache() {
+  cached = null;
+}
+
+/**
+ * Glob match for override keys, so a user can write one entry that hides the
+ * account id and region: `arn:aws:bedrock:*:*:application-inference-profile/x`.
+ */
+function globMatch(pattern, value) {
+  const rx = new RegExp(
+    '^' + pattern.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$',
+  );
+  return rx.test(value);
+}
+
+function overrideAlias(model, map) {
+  for (const [pattern, alias] of Object.entries(map.modelAliases || {})) {
+    if (globMatch(pattern, model)) return alias;
+    // Overrides are usually written without the LiteLLM `converse/` prefix.
+    const bare = model.slice(model.indexOf('arn:aws:bedrock:'));
+    if (globMatch(pattern, bare)) return alias;
+  }
+  return null;
+}
+
+// ── resolution ───────────────────────────────────────────────────────────
+
+/**
+ * Normalize one transcript model id.
+ * Non-gateway ids pass through untouched; gateway ids resolve to an alias, or
+ * to 'unknown' when the mapping is not confident yet.
+ */
+export function resolveModelAlias(rawModel, { env = process.env } = {}) {
+  if (!rawModel) return UNKNOWN_MODEL;
+  const model = String(rawModel);
+  if (!isGatewayModelId(model)) return model;
+
+  const map = loadProfileMap();
+
+  const override = overrideAlias(model, map);
+  if (override) return override;
+
+  const pid = profileIdFrom(model);
+  if (!pid) return UNKNOWN_MODEL;
+
+  const entry = map.learned?.[pid];
+  if (entry?.role) {
+    const alias = aliasForRole(entry.role, env);
+    if (alias) return alias;
+  }
+  return UNKNOWN_MODEL;
+}
+
+// ── learning ─────────────────────────────────────────────────────────────
+
+// A single observation can be wrong: the time-adjacent parent records leak
+// into a naive join, and a mis-set agent definition mislabels one run. Require
+// a few observations that mostly agree before trusting a mapping.
+export const MIN_VOTES = 3;
+export const MIN_AGREEMENT = 0.8;
+
+/** Role named directly by a Task call's `model` parameter. */
+function roleFromModelParam(value) {
+  if (typeof value !== 'string') return null;
+  const v = value.toLowerCase();
+  return ROLES.find((r) => r !== 'main' && v.includes(r)) || null;
+}
+
+/** Role declared in a subagent definition's frontmatter (`model: haiku`). */
+function roleFromAgentType(agentType, cache) {
+  if (!agentType) return null;
+  if (cache.has(agentType)) return cache.get(agentType);
+  let role = null;
+  for (const dir of [join(claudeUserDir(), 'agents'), join(process.cwd(), '.claude', 'agents')]) {
+    const file = join(dir, `${agentType}.md`);
+    if (!existsSync(file)) continue;
+    try {
+      const head = readFileSync(file, 'utf8').slice(0, 2000);
+      const m = /^model:\s*([A-Za-z0-9._-]+)/m.exec(head);
+      if (m) role = roleFromModelParam(m[1]);
+    } catch { /* unreadable definition just yields no vote */ }
+    if (role) break;
+  }
+  cache.set(agentType, role);
+  return role;
+}
+
+function addVote(votes, pid, role) {
+  if (!pid || !role) return;
+  const v = (votes[pid] ||= {});
+  v[role] = (v[role] || 0) + 1;
+}
+
+/**
+ * Read one main transcript: which profile id the session itself ran on, and
+ * which role each Task/Agent tool_use asked for (joined later by tool_use id).
+ */
+async function scanMainTranscript(path, votes, requestedByToolUse, agentTypeCache) {
+  let sawGateway = false;
+  const rl = createInterface({
+    input: createReadStream(path, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  try {
+    for await (const line of rl) {
+      if (!line.includes('arn:aws:bedrock:') && !line.includes('"Task"') && !line.includes('"Agent"')) {
+        continue;
+      }
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const msg = entry.message;
+      if (!msg) continue;
+
+      // The session's own model: the parent side of the transcript.
+      if (msg.model && entry.isSidechain !== true) {
+        const pid = profileIdFrom(msg.model);
+        if (pid) {
+          sawGateway = true;
+          addVote(votes, pid, 'main');
+        }
+      }
+
+      if (!Array.isArray(msg.content)) continue;
+      for (const block of msg.content) {
+        if (!block || block.type !== 'tool_use') continue;
+        if (block.name !== 'Task' && block.name !== 'Agent') continue;
+        const input = block.input || {};
+        const role = roleFromModelParam(input.model)
+          || roleFromAgentType(input.subagent_type, agentTypeCache);
+        if (block.id && role) requestedByToolUse.set(block.id, role);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+  return sawGateway;
+}
+
+/** First profile id used by a subagent transcript (a run uses exactly one). */
+async function subagentProfileId(path) {
+  const rl = createInterface({
+    input: createReadStream(path, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  try {
+    for await (const line of rl) {
+      if (!line.includes('arn:aws:bedrock:')) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const pid = profileIdFrom(entry.message?.model);
+      if (pid) return pid;
+    }
+  } finally {
+    rl.close();
+  }
+  return null;
+}
+
+/** Subagent transcripts a session spawned (mirrors subagent-records layout). */
+async function subagentFiles(sessionPath) {
+  const dir = join(dirname(sessionPath), basename(sessionPath, '.jsonl'), 'subagents');
+  try {
+    return (await readdir(dir)).filter((f) => f.endsWith('.jsonl')).map((f) => join(dir, f));
+  } catch {
+    return [];
+  }
+}
+
+/** Decide a role per profile id once the votes are numerous and consistent. */
+export function tallyVotes(votes, { minVotes = MIN_VOTES, minAgreement = MIN_AGREEMENT } = {}) {
+  const learned = {};
+  for (const [pid, tally] of Object.entries(votes)) {
+    const total = Object.values(tally).reduce((a, b) => a + b, 0);
+    let role = null;
+    let top = 0;
+    for (const [r, n] of Object.entries(tally)) {
+      if (n > top) { top = n; role = r; }
+    }
+    const confident = total >= minVotes && top / total >= minAgreement;
+    learned[pid] = { role: confident ? role : null, votes: tally, total };
+  }
+  return learned;
+}
+
+/**
+ * Learn profile id → role from transcripts and persist the result.
+ *
+ * The join is exact rather than time-windowed: `.meta.json` carries the
+ * `toolUseId` of the Task block that spawned the run, and that block names the
+ * model tier. A subagent transcript uses exactly one profile id, so the run's
+ * id and the requested role identify each other.
+ *
+ * @param {object}   opts
+ * @param {string[]} opts.sessionPaths transcripts to read, newest first
+ * @param {number}   opts.maxSessions  cap on files read (learning is a scan)
+ * @returns {Promise<{learned: object, scannedSessions: number, gateway: boolean}>}
+ */
+export async function learnProfileMapping({ sessionPaths = [], maxSessions = 40 } = {}) {
+  const votes = {};
+  const agentTypeCache = new Map();
+  let scanned = 0;
+  let gateway = false;
+
+  for (const sessionPath of sessionPaths.slice(0, maxSessions)) {
+    const requestedByToolUse = new Map();
+    let sawGateway = false;
+    try {
+      sawGateway = await scanMainTranscript(sessionPath, votes, requestedByToolUse, agentTypeCache);
+    } catch {
+      continue;
+    }
+    scanned += 1;
+
+    for (const jsonl of await subagentFiles(sessionPath)) {
+      let meta = null;
+      try {
+        meta = JSON.parse(await readFile(jsonl.replace(/\.jsonl$/, '.meta.json'), 'utf8'));
+      } catch { /* pre-toolUseId runs simply cast no vote */ }
+      const role = (meta?.toolUseId && requestedByToolUse.get(meta.toolUseId))
+        || roleFromAgentType(meta?.agentType, agentTypeCache);
+      if (!role) continue;
+      const pid = await subagentProfileId(jsonl);
+      if (!pid) continue;
+      sawGateway = true;
+      addVote(votes, pid, role);
+    }
+    if (sawGateway) gateway = true;
+  }
+
+  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);
+  return { learned, scannedSessions: scanned, gateway };
+}

package/src/parser.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { join, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { loadCache, getCached, putCached, saveCache } from './session-cache.js';
+import { resolveModelAlias } from './model-alias.js';
 
 const CLAUDE_DIR = join(homedir(), '.claude', 'projects');
 
@@ -49,7 +50,7 @@ export async function parseSessionFile(filePath) {
 
     requests.set(reqId, {
       requestId: reqId,
-      model: msg.model || 'unknown',
+      model: resolveModelAlias(msg.model),
       inputTokens: usage.input_tokens || 0,
       cacheCreationTokens: usage.cache_creation_input_tokens || 0,
       cacheReadTokens: usage.cache_read_input_tokens || 0,

package/src/route-scan.js

@@ -24,6 +24,7 @@ import { discoverSessionFiles } from './parser.js';
 import { collectSessionRecords } from './session-records.js';
 import { collectSubagentRuns, indexRuns, runsForEpisode } from './subagent-records.js';
 import { estimateCost, modelRank, TIER_TARGET_RANK, tierForRank } from './cost.js';
+import { learnProfileMapping, resetModelAliasCache } from './model-alias.js';
 import { agentPhrase, agentPhraseEn } from './agents.js';
 
 // ── Tier bands (docs/TIER_CRITERIA.md §3) ────────────────────────────────
@@ -331,6 +332,16 @@ export function tierOf(ep, category, th) {
 export async function runRouteScan({ days = 14 } = {}) {
   const files = await discoverSessionFiles({ days });
 
+  // Behind a Bedrock/LiteLLM gateway the transcripts carry an inference-profile
+  // ARN where the model id belongs, which reads as Sonnet and rejects every T1
+  // rule. Refresh the profile→role mapping before parsing so this scan resolves
+  // those ids; on a direct-API machine it finds nothing and writes nothing.
+  resetModelAliasCache();
+  try {
+    await learnProfileMapping({ sessionPaths: files.map((f) => f.path) });
+  } catch { /* learning is an optimization — the scan still runs without it */ }
+  resetModelAliasCache();
+
   // Pass 1 — collect episodes (needed up front: thresholds are calibrated
   // from the full window's output distribution before any tiering).
   const all = []; // { ep, projectDir, sessionPath }

package/src/session-records.js

@@ -9,10 +9,16 @@
 
 import { createReadStream } from 'node:fs';
 import { createInterface } from 'node:readline';
+import { resolveModelAlias } from './model-alias.js';
 
-/** Strip context-window suffixes like "[1m]" so model ids compare cleanly. */
+/**
+ * Strip context-window suffixes like "[1m]" so model ids compare cleanly, and
+ * turn a gateway inference-profile ARN back into a Claude alias. Ids that are
+ * already Claude aliases pass through untouched.
+ */
 export function normalizeModelId(model) {
-  return String(model || 'unknown').replace(/\[[^\]]*\]$/, '');
+  const resolved = resolveModelAlias(model || 'unknown');
+  return String(resolved).replace(/\[[^\]]*\]$/, '');
 }
 
 /** Extract plain text from a Claude transcript message content field. */