jeo-code 0.8.16 → 0.8.17

package/CHANGELOG.md

@@ -6,6 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+## [0.8.17] - 2026-07-09
+_"서브에이전트 이용해. 병렬루 부가 나머지모두 개선하고 검증후 배포까지하자" — a prior 4-way parallel subagent cross-verification pass found the README `[!CAUTION]` routing-lock block (added this session for "프롬프트 라우팅이 한번 정해지면 안바뀌는데?") was directionally correct but had 2 real inaccuracies, plus a concrete test-coverage gap: every existing pin/override regression test drove the lock via the `--model` CLI startup flag, never via typing `/model <name>` as an interactive slash command mid-session, and none proved persistence across 3+ consecutive turns._
+
+### Fixed
+- **README `/route on` semantics corrected** (`README.md`, `README.ko.md`, `README.ja.md`, `README.zh.md`) — the caution block previously said the model pin releases "until `/route on` with no pin active", which has the mechanism backwards: `/route on` (`src/commands/launch/route-slash.ts:93-98`) sets `sessionRouteOverride = true`, which *outranks* an active `sessionModel` pin without clearing it — the pin reasserts itself the instant `/route off` runs (confirmed by the existing `test/launch-prompt-routing.test.ts` "/route on then /route off" regression). Only `/model auto` actually clears the pin (`sessionModel = undefined`).
+- **README tier-fallback claim scoped correctly** — the caution block previously implied any tier missing a `roles.*` entry falls back to `defaultModel` on every turn. `resolveTierModel` (`src/agent/prompt-router.ts:464-472`) only guarantees that for the `standard` tier; `high` and `complex` first run a live credentialed-model scan (`strongestMidTierCredentialed` / `strongestCredentialed`) before falling back, so they can still resolve to a different model each turn even when unconfigured. Reworded in all 4 languages; also fixed a KO/JA translation drift that narrowed "a tier" to "상위 티어"/"上位ティア" (upper tier), which had no counterpart in the EN/ZH text.
+
+### Added
+- **Mid-session `/model <name>` slash-command lock + persistence coverage** (`test/launch-prompt-routing.test.ts`) — 3 new tests proving the pin set by literally typing `/model <name>` (not just the `--model` CLI flag) holds on the very next turn, persists across 3+ consecutive subsequent turns with no further commands, and correctly cycles through pin → `/model auto` release → re-pin to a different model.
+- **Tier-resolution freshness + scoping coverage** (`test/prompt-router-tiers.test.ts`) — 2 new tests proving `resolveTierModel` has no cross-call caching (interleaved trivial/complex/trivial calls never bleed into each other) and asserting the standard/high/complex fallback-boundary contrast in one place (`standard` and `high` fall through to `defaultModel` on an OpenAI-only fixture with no mid-class model, `complex` does not) as a regression guard against this exact scope-of-claim mistake recurring silently.
+
+### Verified
+- `bun test test/launch-prompt-routing.test.ts` — 38 pass / 0 fail (35 pre-existing + 3 new).
+- `bun test test/prompt-router-tiers.test.ts test/prompt-router.test.ts` — 86 pass / 0 fail (84 pre-existing + 2 new).
+- Full `bun test` — 2877 pass / 0 fail across 290 files.
+- `bun run typecheck` — no errors.
+- Live PTY re-verification (`bun src/cli.ts`, isolated `JEO_CONFIG_DIR`, real Anthropic credentials): trivial prompt → routed to `roles.smol`; `/model claude-sonnet-4-6` → next trivial prompt stayed pinned (no `[route]` notice, confirmed via raw byte-stream regex search, not just screen snapshot); `/model auto` → next trivial prompt re-routed to `roles.smol` again. Closes the one claim that was previously only inferred from a code comment.
+
 ## [0.8.16] - 2026-07-09
 _"jeo code의 computer use 기능은 / 명령어로 설정할수있도록하고, 실동작검증까지진행해줘" — the desktop-automation `computer` tool was only togglable by hand-editing `computer.enabled` in `~/.jeo/config.json`; there was no in-session way to enable it for a single run without leaving a permanent config change behind._
 

package/README.ja.md

@@ -90,6 +90,9 @@ jeo --tmux               # 独立した tmux セッションで実行
 | `/theme` · `/config` · `/help` | テーマ、ランタイム設定、ヘルプ |
 | `jeo autopilot status` | スコア方向、keep/revert 数、次アクションを示す ratchet ステータスフィールド |
 
+> [!CAUTION]
+> **`/model <name>` で特定モデルを手動指定すると、そのセッション中ルーティングが固定されます。** プロンプトルーティング(`/route`)はモデルが手動固定されていない間のみ毎ターン再評価されます。`/model <name>` で特定モデルを選ぶとその選択が固定され、`/model auto`(ピンを完全に解除)を実行するか、`/route on`(ピンを消さずに優先度だけ上げる — `/route off` した瞬間ピンが復活)を実行するまでルーティングは切り替わりません。`roles.*` 未設定時に `defaultModel` へ確定フォールバックするのは `standard` ティアのみで、`high`/`complex` ティアはフォールバック前にライブでクレデンシャル済みの最強モデルを先に探索するため、未設定でも毎ターン別モデルに着地することがあります。
+
 ## Spec-first ワークフロー
 
 要件 → プラン → 承認 → 実行 → 検証が `.jeo/state/` で繋がり、各ハンドオフに**ブロック可能な本物のゲート**があります:
@@ -262,11 +265,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.17]** (2026-07-09) — "서브에이전트 이용해. 병렬루 부가 나머지모두 개선하고 검증후 배포까지하자" — a prior 4-way parallel subagent cross-verification pass found the README `[!CAUTION]` routing-lock block (added this session for "프롬프트 라우팅이 한번 정해지면 안바뀌는데?") was directionally correct but had 2 real inaccuracies, plus a concrete test-coverage gap: every existing pin/override regression test drove the lock via the `--model` CLI startup flag, never via typing `/model <name>` as an interactive slash command mid-session, and none proved persistence across 3+ consecutive turns.
 - **[0.8.16]** (2026-07-09) — "jeo code의 computer use 기능은 / 명령어로 설정할수있도록하고, 실동작검증까지진행해줘" — the desktop-automation `computer` tool was only togglable by hand-editing `computer.enabled` in `~/.jeo/config.json`; there was no in-session way to enable it for a single run without leaving a permanent config change behind.
 - **[0.8.15]** (2026-07-09) — "api 인증 모델도 사용가능하도록 딥리서치하고 개선해줘" — traced the API-authenticated GPT path to a routing catalog gap: `GET /models` with an OpenAI API key or an OpenAI-compatible provider returned real account-scoped model ids, and `/model` could show/pin them, but prompt routing still built its auto-select pools from static `MODEL_CATALOG` rows only. A custom `openaiBaseUrl` made this worse by treating every public OpenAI row as servable, so routing could choose `gpt-*`/`o*` ids that the configured local/Azure/proxy endpoint never listed.
 - **[0.8.14]** (2026-07-09) — "GPT 연결 실패가 여전히 무응답으로 끝나는 케이스를 잡아줘" — traced the remaining GPT/routing failure path to post-call continuity: the route target could be credentialed and servable, but still end a turn with a recoverable terminal result such as plain `OpenAI returned no content`, rate/quota pressure, model unavailable/not found, or an invalid agent-tool response. jeo already knew the prompt tier and equivalent credentialed fallbacks, but it only applied that fallback before the model call. After the call failed, the turn stopped instead of trying another model in the same tier.
 - **[0.8.13]** (2026-07-09) — "테스트검증 jeo --tmux 로 진행해줘" — traced a routing recovery weakness that survived the earlier credential, servability, and local reachability vetoes: once a configured route target was rejected, jeo threw away the whole routing decision and dropped to the session/default model even when the same prompt tier had another credentialed, servable model available. That kept turns working, but it also silently undid routing's cost/latency goal and made `/route why` less useful because the recorded decision was a fallback note instead of the actual model used.
-- **[0.8.12]** (2026-07-08) — "제오코드에서 oauth 지피티 모델 연결이 안되는데 원인파악해서 개선해" — root-caused a structural drift bug: OpenAI's live Codex models endpoint (`chatgpt.com/backend-api/codex/models`, the SAME endpoint the `/model` picker discovers from) had shipped `gpt-5.4-mini` alongside `gpt-5.5`/`gpt-5.4`, but jeo's static OAuth allow-list (`CODEX_MODELS`) hadn't caught up — the picker correctly listed the model (straight from that live endpoint), but selecting or calling it then hit a hard-coded `CODEX_MODELS.includes(...)` gate that rejected it with "OpenAI OAuth credential only supports Codex models", even though the account's own OAuth token genuinely serves it. This is a whole class of bug: it recurs every time OpenAI ships a new Codex model between jeo releases, and previously required a jeo update to fix each time.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -91,6 +91,9 @@ jeo --tmux               # 독립 tmux 세션에서 실행
 | `/theme` · `/config` · `/help` | 테마, 런타임 설정, 도움말 |
 | `jeo autopilot status` | 점수 방향, keep/revert 횟수, 다음 액션을 보여주는 ratchet 상태 필드 |
 
+> [!CAUTION]
+> **`/model <name>`으로 특정 모델을 수동 지정하면 그 세션 동안 라우팅이 고정됩니다.** 프롬프트 라우팅(`/route`)은 모델이 수동으로 고정되지 않은 동안만 매 턴 재평가됩니다. `/model <name>`으로 특정 모델을 선택하면 그 선택이 그대로 고정되며, `/model auto`(핀을 완전히 해제)를 실행하거나 `/route on`(핀을 지우지 않고 그보다 우선순위를 높임 — `/route off` 하는 즉시 핀이 다시 살아남)을 실행하기 전까지는 라우팅이 다시 전환되지 않습니다. `roles.*` 항목 미설정 시 `defaultModel`로 확정 폴백되는 건 `standard` 티어뿐이며, `high`/`complex` 티어는 폴백 전에 실시간으로 크레덴셜된 가장 강력한 모델을 먼저 탐색하므로, 설정이 없어도 매 턴 다른 모델로 갈 수 있습니다.
+
 ## Spec-first 워크플로
 
 요구사항 → 플랜 → 승인 → 실행 → 검증이 `.jeo/state/`로 이어지며, 모든 핸드오프에 **차단 가능한 진짜 게이트**가 있습니다:
@@ -263,11 +266,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.17]** (2026-07-09) — "서브에이전트 이용해. 병렬루 부가 나머지모두 개선하고 검증후 배포까지하자" — a prior 4-way parallel subagent cross-verification pass found the README `[!CAUTION]` routing-lock block (added this session for "프롬프트 라우팅이 한번 정해지면 안바뀌는데?") was directionally correct but had 2 real inaccuracies, plus a concrete test-coverage gap: every existing pin/override regression test drove the lock via the `--model` CLI startup flag, never via typing `/model <name>` as an interactive slash command mid-session, and none proved persistence across 3+ consecutive turns.
 - **[0.8.16]** (2026-07-09) — "jeo code의 computer use 기능은 / 명령어로 설정할수있도록하고, 실동작검증까지진행해줘" — the desktop-automation `computer` tool was only togglable by hand-editing `computer.enabled` in `~/.jeo/config.json`; there was no in-session way to enable it for a single run without leaving a permanent config change behind.
 - **[0.8.15]** (2026-07-09) — "api 인증 모델도 사용가능하도록 딥리서치하고 개선해줘" — traced the API-authenticated GPT path to a routing catalog gap: `GET /models` with an OpenAI API key or an OpenAI-compatible provider returned real account-scoped model ids, and `/model` could show/pin them, but prompt routing still built its auto-select pools from static `MODEL_CATALOG` rows only. A custom `openaiBaseUrl` made this worse by treating every public OpenAI row as servable, so routing could choose `gpt-*`/`o*` ids that the configured local/Azure/proxy endpoint never listed.
 - **[0.8.14]** (2026-07-09) — "GPT 연결 실패가 여전히 무응답으로 끝나는 케이스를 잡아줘" — traced the remaining GPT/routing failure path to post-call continuity: the route target could be credentialed and servable, but still end a turn with a recoverable terminal result such as plain `OpenAI returned no content`, rate/quota pressure, model unavailable/not found, or an invalid agent-tool response. jeo already knew the prompt tier and equivalent credentialed fallbacks, but it only applied that fallback before the model call. After the call failed, the turn stopped instead of trying another model in the same tier.
 - **[0.8.13]** (2026-07-09) — "테스트검증 jeo --tmux 로 진행해줘" — traced a routing recovery weakness that survived the earlier credential, servability, and local reachability vetoes: once a configured route target was rejected, jeo threw away the whole routing decision and dropped to the session/default model even when the same prompt tier had another credentialed, servable model available. That kept turns working, but it also silently undid routing's cost/latency goal and made `/route why` less useful because the recorded decision was a fallback note instead of the actual model used.
-- **[0.8.12]** (2026-07-08) — "제오코드에서 oauth 지피티 모델 연결이 안되는데 원인파악해서 개선해" — root-caused a structural drift bug: OpenAI's live Codex models endpoint (`chatgpt.com/backend-api/codex/models`, the SAME endpoint the `/model` picker discovers from) had shipped `gpt-5.4-mini` alongside `gpt-5.5`/`gpt-5.4`, but jeo's static OAuth allow-list (`CODEX_MODELS`) hadn't caught up — the picker correctly listed the model (straight from that live endpoint), but selecting or calling it then hit a hard-coded `CODEX_MODELS.includes(...)` gate that rejected it with "OpenAI OAuth credential only supports Codex models", even though the account's own OAuth token genuinely serves it. This is a whole class of bug: it recurs every time OpenAI ships a new Codex model between jeo releases, and previously required a jeo update to fix each time.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -96,6 +96,9 @@ Inside the `jeo` REPL (Tab autocompletes; `/` opens the palette).
 | `/theme` · `/config` · `/help` | Theme, runtime config, help |
 | `jeo autopilot status` | Ratchet status field with score direction, keep/revert counts, and next action |
 
+> [!CAUTION]
+> **`/model <name>` locks routing for the rest of the session.** Prompt routing (`/route`) only re-evaluates per turn while no model is manually pinned. Picking a specific model via `/model <name>` freezes that choice — routing will *not* switch away from it again until you run `/model auto` (which clears the pin), or `/route on` (which *outranks* an active pin without clearing it — the pin reasserts itself the moment you run `/route off`). Missing a `roles.*` entry only guarantees a `defaultModel` fallback on the `standard` tier; the `high`/`complex` tiers first scan for the strongest live-credentialed model before falling back, so they can still land on a different model each turn even when unconfigured.
+
 ## Spec-first workflow
 
 Requirements → plan → approval → execution → verification, carried through `.jeo/state/` with **real, blocking gates** at every handoff:
@@ -270,11 +273,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.17]** (2026-07-09) — "서브에이전트 이용해. 병렬루 부가 나머지모두 개선하고 검증후 배포까지하자" — a prior 4-way parallel subagent cross-verification pass found the README `[!CAUTION]` routing-lock block (added this session for "프롬프트 라우팅이 한번 정해지면 안바뀌는데?") was directionally correct but had 2 real inaccuracies, plus a concrete test-coverage gap: every existing pin/override regression test drove the lock via the `--model` CLI startup flag, never via typing `/model <name>` as an interactive slash command mid-session, and none proved persistence across 3+ consecutive turns.
 - **[0.8.16]** (2026-07-09) — "jeo code의 computer use 기능은 / 명령어로 설정할수있도록하고, 실동작검증까지진행해줘" — the desktop-automation `computer` tool was only togglable by hand-editing `computer.enabled` in `~/.jeo/config.json`; there was no in-session way to enable it for a single run without leaving a permanent config change behind.
 - **[0.8.15]** (2026-07-09) — "api 인증 모델도 사용가능하도록 딥리서치하고 개선해줘" — traced the API-authenticated GPT path to a routing catalog gap: `GET /models` with an OpenAI API key or an OpenAI-compatible provider returned real account-scoped model ids, and `/model` could show/pin them, but prompt routing still built its auto-select pools from static `MODEL_CATALOG` rows only. A custom `openaiBaseUrl` made this worse by treating every public OpenAI row as servable, so routing could choose `gpt-*`/`o*` ids that the configured local/Azure/proxy endpoint never listed.
 - **[0.8.14]** (2026-07-09) — "GPT 연결 실패가 여전히 무응답으로 끝나는 케이스를 잡아줘" — traced the remaining GPT/routing failure path to post-call continuity: the route target could be credentialed and servable, but still end a turn with a recoverable terminal result such as plain `OpenAI returned no content`, rate/quota pressure, model unavailable/not found, or an invalid agent-tool response. jeo already knew the prompt tier and equivalent credentialed fallbacks, but it only applied that fallback before the model call. After the call failed, the turn stopped instead of trying another model in the same tier.
 - **[0.8.13]** (2026-07-09) — "테스트검증 jeo --tmux 로 진행해줘" — traced a routing recovery weakness that survived the earlier credential, servability, and local reachability vetoes: once a configured route target was rejected, jeo threw away the whole routing decision and dropped to the session/default model even when the same prompt tier had another credentialed, servable model available. That kept turns working, but it also silently undid routing's cost/latency goal and made `/route why` less useful because the recorded decision was a fallback note instead of the actual model used.
-- **[0.8.12]** (2026-07-08) — "제오코드에서 oauth 지피티 모델 연결이 안되는데 원인파악해서 개선해" — root-caused a structural drift bug: OpenAI's live Codex models endpoint (`chatgpt.com/backend-api/codex/models`, the SAME endpoint the `/model` picker discovers from) had shipped `gpt-5.4-mini` alongside `gpt-5.5`/`gpt-5.4`, but jeo's static OAuth allow-list (`CODEX_MODELS`) hadn't caught up — the picker correctly listed the model (straight from that live endpoint), but selecting or calling it then hit a hard-coded `CODEX_MODELS.includes(...)` gate that rejected it with "OpenAI OAuth credential only supports Codex models", even though the account's own OAuth token genuinely serves it. This is a whole class of bug: it recurs every time OpenAI ships a new Codex model between jeo releases, and previously required a jeo update to fix each time.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -90,6 +90,9 @@ jeo --tmux               # 在独立 tmux 会话中运行
 | `/theme` · `/config` · `/help` | 主题、运行时配置、帮助 |
 | `jeo autopilot status` | 显示分数方向、keep/revert 次数和下一步动作的 ratchet 状态字段 |
 
+> [!CAUTION]
+> **通过 `/model <name>` 手动指定模型后，路由会在本会话内保持锁定。** Prompt routing(`/route`)只在没有手动锁定模型时才会逐轮重新评估。用 `/model <name>` 选定具体模型后，该选择会被锁定 — 直到你运行 `/model auto`(彻底解除锁定)，或运行 `/route on`(不会清除锁定，只是优先级更高 — 一旦运行 `/route off`，锁定会立刻恢复)之前，路由都不会再切换。未配置 `roles.*` 条目时，只有 `standard` 层级会确定性地退回到 `defaultModel`；`high`/`complex` 层级会先实时扫描已配置凭证中最强的可用模型再决定是否回退，所以即使未配置，也可能每轮落到不同的模型上。
+
 ## Spec-first 工作流
 
 需求 → 计划 → 批准 → 执行 → 验证，经由 `.jeo/state/` 串联，每次交接都有**可阻断的真实门禁**:
@@ -262,11 +265,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.8.17]** (2026-07-09) — "서브에이전트 이용해. 병렬루 부가 나머지모두 개선하고 검증후 배포까지하자" — a prior 4-way parallel subagent cross-verification pass found the README `[!CAUTION]` routing-lock block (added this session for "프롬프트 라우팅이 한번 정해지면 안바뀌는데?") was directionally correct but had 2 real inaccuracies, plus a concrete test-coverage gap: every existing pin/override regression test drove the lock via the `--model` CLI startup flag, never via typing `/model <name>` as an interactive slash command mid-session, and none proved persistence across 3+ consecutive turns.
 - **[0.8.16]** (2026-07-09) — "jeo code의 computer use 기능은 / 명령어로 설정할수있도록하고, 실동작검증까지진행해줘" — the desktop-automation `computer` tool was only togglable by hand-editing `computer.enabled` in `~/.jeo/config.json`; there was no in-session way to enable it for a single run without leaving a permanent config change behind.
 - **[0.8.15]** (2026-07-09) — "api 인증 모델도 사용가능하도록 딥리서치하고 개선해줘" — traced the API-authenticated GPT path to a routing catalog gap: `GET /models` with an OpenAI API key or an OpenAI-compatible provider returned real account-scoped model ids, and `/model` could show/pin them, but prompt routing still built its auto-select pools from static `MODEL_CATALOG` rows only. A custom `openaiBaseUrl` made this worse by treating every public OpenAI row as servable, so routing could choose `gpt-*`/`o*` ids that the configured local/Azure/proxy endpoint never listed.
 - **[0.8.14]** (2026-07-09) — "GPT 연결 실패가 여전히 무응답으로 끝나는 케이스를 잡아줘" — traced the remaining GPT/routing failure path to post-call continuity: the route target could be credentialed and servable, but still end a turn with a recoverable terminal result such as plain `OpenAI returned no content`, rate/quota pressure, model unavailable/not found, or an invalid agent-tool response. jeo already knew the prompt tier and equivalent credentialed fallbacks, but it only applied that fallback before the model call. After the call failed, the turn stopped instead of trying another model in the same tier.
 - **[0.8.13]** (2026-07-09) — "테스트검증 jeo --tmux 로 진행해줘" — traced a routing recovery weakness that survived the earlier credential, servability, and local reachability vetoes: once a configured route target was rejected, jeo threw away the whole routing decision and dropped to the session/default model even when the same prompt tier had another credentialed, servable model available. That kept turns working, but it also silently undid routing's cost/latency goal and made `/route why` less useful because the recorded decision was a fallback note instead of the actual model used.
-- **[0.8.12]** (2026-07-08) — "제오코드에서 oauth 지피티 모델 연결이 안되는데 원인파악해서 개선해" — root-caused a structural drift bug: OpenAI's live Codex models endpoint (`chatgpt.com/backend-api/codex/models`, the SAME endpoint the `/model` picker discovers from) had shipped `gpt-5.4-mini` alongside `gpt-5.5`/`gpt-5.4`, but jeo's static OAuth allow-list (`CODEX_MODELS`) hadn't caught up — the picker correctly listed the model (straight from that live endpoint), but selecting or calling it then hit a hard-coded `CODEX_MODELS.includes(...)` gate that rejected it with "OpenAI OAuth credential only supports Codex models", even though the account's own OAuth token genuinely serves it. This is a whole class of bug: it recurs every time OpenAI ships a new Codex model between jeo releases, and previously required a jeo update to fix each time.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/route-history.ts

@@ -0,0 +1,107 @@
+/**
+ * Routing decision history tracker — maintains a bounded FIFO queue of recent
+ * routing decisions for `/route history` visibility and performance analysis.
+ *
+ * Session-scoped (one per REPL), not persisted to config.
+ */
+
+import type { RouteDecision } from "./prompt-router";
+
+export interface RouteHistoryEntry extends RouteDecision {
+  timestamp: number; // Date.now()
+  turnNumber: number; // 1-indexed turn in this session
+}
+
+/**
+ * Bounded FIFO queue of routing decisions. Oldest entries are dropped when
+ * the queue exceeds `maxSize`.
+ */
+export class RouteHistory {
+  private entries: RouteHistoryEntry[] = [];
+  private turnNumber = 0;
+  readonly maxSize: number;
+
+  constructor(maxSize: number = 10) {
+    this.maxSize = Math.max(1, maxSize);
+  }
+
+  /**
+   * Record a routing decision. Increments the turn counter and adds the entry
+   * to the queue, dropping the oldest if necessary.
+   */
+  add(decision: RouteDecision): void {
+    this.turnNumber++;
+    const entry: RouteHistoryEntry = {
+      ...decision,
+      timestamp: Date.now(),
+      turnNumber: this.turnNumber,
+    };
+    this.entries.push(entry);
+    if (this.entries.length > this.maxSize) {
+      this.entries.shift();
+    }
+  }
+
+  /**
+   * Get all recorded entries in chronological order (oldest first).
+   */
+  getAll(): RouteHistoryEntry[] {
+    return [...this.entries];
+  }
+
+  /**
+   * Get the most recent entry, if any.
+   */
+  getLast(): RouteHistoryEntry | undefined {
+    return this.entries[this.entries.length - 1];
+  }
+
+  /**
+   * Get entries for a specific model.
+   */
+  getByModel(model: string): RouteHistoryEntry[] {
+    return this.entries.filter((e) => e.model === model);
+  }
+
+  /**
+   * Get entries for a specific tier.
+   */
+  getByTier(tier: string): RouteHistoryEntry[] {
+    return this.entries.filter((e) => e.tier === tier);
+  }
+
+  /**
+   * Compute statistics over the history.
+   */
+  getStats(): {
+    totalDecisions: number;
+    modelFrequency: Record<string, number>;
+    tierFrequency: Record<string, number>;
+    averageConfidence: number;
+  } {
+    const modelFreq: Record<string, number> = {};
+    const tierFreq: Record<string, number> = {};
+    let totalConfidence = 0;
+
+    for (const entry of this.entries) {
+      modelFreq[entry.model] = (modelFreq[entry.model] ?? 0) + 1;
+      tierFreq[entry.tier] = (tierFreq[entry.tier] ?? 0) + 1;
+      totalConfidence += entry.confidence;
+    }
+
+    return {
+      totalDecisions: this.entries.length,
+      modelFrequency: modelFreq,
+      tierFrequency: tierFreq,
+      averageConfidence: this.entries.length > 0 ? totalConfidence / this.entries.length : 0,
+    };
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear(): void {
+    this.entries = [];
+    this.turnNumber = 0;
+  }
+}

package/src/agent/subagents.ts

@@ -16,6 +16,9 @@ import architectPrompt from "../prompts/agents/architect.md" with { type: "text"
 import criticPrompt from "../prompts/agents/critic.md" with { type: "text" };
 import executorPrompt from "../prompts/agents/executor.md" with { type: "text" };
 import plannerPrompt from "../prompts/agents/planner.md" with { type: "text" };
+import type { PromptTier } from "./prompt-router";
+
+const PROMPT_ROUTE_TIERS = ["trivial", "standard", "high", "complex"] as const satisfies readonly PromptTier[];
 
 export interface SubagentRole {
   /** Stable id used in config + `/agents <id>`. */
@@ -362,9 +365,9 @@ export function clearSubagentSetting(config: Pick<Config, "subagents">, roleId:
   return subs;
 }
 
-/** One pickable apply-target: the global default or a subagent role. */
+/** One pickable apply-target: the global default, a prompt-routing tier, or a subagent role. */
 export interface ApplyTargetChoice {
-  /** "default" or a subagent role id. */
+  /** "default", "routing:<tier>", or a subagent role id. */
   value: string;
   label: string;
   /** Right-aligned hint: the target's CURRENT model (so the picker doubles as a viewer). */
@@ -378,18 +381,32 @@ export interface ApplyTargetChoice {
  * read-and-change panel for existing role assignments. Pure — testable.
  */
 export function applyTargetChoices(
-  config: Pick<Config, "defaultModel" | "subagents" | "thinkingLevel">,
+  config: Pick<Config, "defaultModel" | "subagents" | "thinkingLevel" | "routing" | "roles"> &
+    Partial<Pick<Config, "providers" | "oauth" | "openaiBaseUrl">>,
 ): ApplyTargetChoice[] {
   const roleThink = (id: string): string => {
     const t = resolveSubagentThinking(id, config);
     return t ? ` (${t})` : " (inherit)";
   };
+  const routeThink = (tier: PromptTier): string => {
+    const t = config.routing?.tiers?.[tier]?.thinking;
+    return t ? ` (${t})` : " (auto thinking)";
+  };
+  // Lazy load keeps the existing subagents→prompt-router dependency from
+  // becoming an eager module cycle; resolveSubagentModel uses the same pattern.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { resolveTierModel } = require("./prompt-router");
   return [
     {
       value: "default",
       label: "default — every session",
       hint: `${config.defaultModel} (${config.thinkingLevel ?? "medium"})`,
     },
+    ...PROMPT_ROUTE_TIERS.map(tier => ({
+      value: `routing:${tier}`,
+      label: `route ${tier} — PromptRouter tier`,
+      hint: `${config.routing?.tiers?.[tier]?.model ?? resolveTierModel(tier, config)}${config.routing?.tiers?.[tier]?.model ? "" : " (auto)"}${routeThink(tier)}`,
+    })),
     ...allSubagentRoles(config).map(role => ({
       value: role.id,
       label: `subagent ${role.id} — ${role.title}`,

package/src/ai/providers/anthropic-compatible.ts

@@ -1,5 +1,7 @@
 import type { ProviderAdapter, CallOptions, ProviderName } from "../types";
 import { anthropicAdapter } from "./anthropic";
+import { relabelProviderError } from "./errors";
+import { companyLabel } from "../model-catalog";
 
 /**
  * Factory for Anthropic-Messages-compatible providers (z.ai, MiniMax, …). They speak
@@ -11,17 +13,32 @@ import { anthropicAdapter } from "./anthropic";
  */
 export function makeAnthropicCompatibleAdapter(opts: { name: ProviderName; baseUrl: string }): ProviderAdapter {
   const prefix = `${opts.name}/`;
+  const label = companyLabel(opts.name);
   const prep = (o: CallOptions): CallOptions => ({
     ...o,
     model: o.model.startsWith(prefix) ? o.model.slice(prefix.length) : o.model,
     baseUrl: o.baseUrl ?? opts.baseUrl,
   });
+  // `anthropicAdapter` hardcodes "Anthropic" as the provider label on every thrown
+  // ProviderHttpError/ProviderStreamError — relabel to the REAL backend (e.g. "Tencent",
+  // "z.ai") so friendlyProviderError/the fallback classifier/the user all see the true
+  // account that needs attention (auth, billing, rate limit) instead of Anthropic's.
   return {
     name: opts.name,
     supportsNativeTools: anthropicAdapter.supportsNativeTools,
-    call: (messages, options, credential) => anthropicAdapter.call(messages, prep(options), credential),
+    call: async (messages, options, credential) => {
+      try {
+        return await anthropicAdapter.call(messages, prep(options), credential);
+      } catch (err) {
+        throw relabelProviderError(err, label);
+      }
+    },
     async *stream(messages, options, credential) {
-      yield* anthropicAdapter.stream!(messages, prep(options), credential);
+      try {
+        yield* anthropicAdapter.stream!(messages, prep(options), credential);
+      } catch (err) {
+        throw relabelProviderError(err, label);
+      }
     },
   };
 }

package/src/ai/providers/errors.ts

@@ -12,12 +12,20 @@ export class ProviderHttpError extends Error {
   readonly provider: string;
   /** Server-directed backoff from a `Retry-After` header, in ms (if present). */
   readonly retryAfterMs?: number;
+  /** Raw response body (or synthesized detail text) — kept separately so a caller can
+   *  reconstruct this error under a DIFFERENT provider label (see `relabelProviderError`)
+   *  without re-parsing it back out of the composed `.message`. */
+  readonly detail: string;
+  /** Optional context suffix (e.g. "(stream)") — see `detail`'s rationale. */
+  readonly context?: string;
   constructor(provider: string, status: number, detail: string, context?: string, retryAfterMs?: number) {
     super(`${provider} request failed (HTTP ${status})${context ? ` ${context}` : ""}: ${detail}`);
     this.name = "ProviderHttpError";
     this.status = status;
     this.provider = provider;
     this.retryAfterMs = retryAfterMs;
+    this.detail = detail;
+    this.context = context;
   }
 }
 
@@ -39,6 +47,10 @@ export class ProviderStreamError extends Error {
   readonly status: number;
   readonly provider: string;
   readonly code?: string;
+  /** Raw stream-error message (pre-composition) — see `ProviderHttpError.detail`'s
+   *  rationale; lets `relabelProviderError` reconstruct this error under a different
+   *  provider label without re-parsing `.message`. */
+  readonly rawMessage: string;
   /** `explicitStatus` lets a caller pass an ALREADY-numeric provider status (e.g. Google's
    *  `error.code` on a `google.rpc.Status` envelope — 429/500/503) instead of relying on the
    *  OpenAI-specific `code === "rate_limit_exceeded"` string heuristic below, which only
@@ -49,9 +61,31 @@ export class ProviderStreamError extends Error {
     this.status = explicitStatus ?? (code === "rate_limit_exceeded" ? 429 : 500);
     this.provider = provider;
     this.code = code;
+    this.rawMessage = message;
   }
 }
 
+/** Rebuild `err` under a DIFFERENT provider label — both `.provider` and the composed
+ *  `.message` are corrected, not just the field (a caller matching on message text, or
+ *  a user reading the raw error, must see the TRUE provider either way). Used by the
+ *  Anthropic/OpenAI-compatible adapter factories (`makeAnthropicCompatibleAdapter`,
+ *  `makeOpenAICompatibleAdapter`): they delegate to `anthropicAdapter`/`openaiAdapter`,
+ *  which hardcode "Anthropic"/"OpenAI" at their `ProviderHttpError`/`ProviderStreamError`
+ *  construction sites — so a groq/tencent/zai/deepseek/… failure previously surfaced as
+ *  "Anthropic rejected the credential" or "OpenAI requires billing", sending the user to
+ *  fix the WRONG account. Non-`ProviderHttpError`/`ProviderStreamError` errors (bare
+ *  `Error`, network failures, etc.) pass through unchanged — those never carried a
+ *  hardcoded label to begin with. */
+export function relabelProviderError(err: unknown, provider: string): unknown {
+  if (err instanceof ProviderHttpError) {
+    return new ProviderHttpError(provider, err.status, err.detail, err.context, err.retryAfterMs);
+  }
+  if (err instanceof ProviderStreamError) {
+    return new ProviderStreamError(provider, err.rawMessage, err.code, err.status);
+  }
+  return err;
+}
+
 /**
  * Parse a `Retry-After` header into ms. Supports the delta-seconds form
  * (`"5"`) and the HTTP-date form (`"Wed, 21 Oct 2025 07:28:00 GMT"`).

package/src/ai/providers/kimi.ts

@@ -3,6 +3,8 @@ import { getKimiCommonHeaders } from "../../auth/flows/kimi";
 import type { CallOptions, ProviderAdapter } from "../types";
 import { anthropicAdapter } from "./anthropic";
 import { makeOpenAICompatibleAdapter } from "./openai-compatible";
+import { relabelProviderError } from "./errors";
+import { companyLabel } from "../model-catalog";
 
 /**
  * Kimi (Moonshot) — two credential-dependent backends (gjc parity):
@@ -18,6 +20,7 @@ export const KIMI_BASE_URL = "https://api.moonshot.ai/v1";
 export const KIMI_ANTHROPIC_BASE_URL = "https://api.kimi.com/coding";
 
 const openaiCompatKimi = makeOpenAICompatibleAdapter({ name: "kimi", baseUrl: KIMI_BASE_URL });
+const KIMI_LABEL = companyLabel("kimi");
 
 /** Route the `kimi/` prefix + OAuth base/headers onto the anthropic adapter. */
 // ponytail: model ids pass through untranslated — the moonshot catalog ids (kimi-latest, …)
@@ -33,19 +36,31 @@ function prepOAuth(o: CallOptions): CallOptions {
 }
 
 /** Dispatch on credential kind: OAuth → Kimi Code Anthropic endpoint; else the
- *  original OpenAI-compatible moonshot adapter (API-key behavior unchanged). */
+ *  original OpenAI-compatible moonshot adapter (API-key behavior unchanged).
+ *  The OAuth path delegates to `anthropicAdapter`, which hardcodes "Anthropic" at
+ *  its `ProviderHttpError`/`ProviderStreamError` construction sites — relabel to
+ *  "Moonshot" (same fix as `makeAnthropicCompatibleAdapter`/`makeOpenAICompatibleAdapter`)
+ *  so a Kimi Code failure never sends the user to fix their Anthropic account. */
 export const kimiAdapter: ProviderAdapter = {
   name: "kimi",
   supportsNativeTools: openaiCompatKimi.supportsNativeTools,
-  call: (messages, options, credential) =>
-    credential.kind === "oauth"
-      ? anthropicAdapter.call(messages, prepOAuth(options), credential)
-      : openaiCompatKimi.call(messages, options, credential),
+  call: async (messages, options, credential) => {
+    if (credential.kind !== "oauth") return openaiCompatKimi.call(messages, options, credential);
+    try {
+      return await anthropicAdapter.call(messages, prepOAuth(options), credential);
+    } catch (err) {
+      throw relabelProviderError(err, KIMI_LABEL);
+    }
+  },
   async *stream(messages, options, credential) {
-    if (credential.kind === "oauth") {
-      yield* anthropicAdapter.stream!(messages, prepOAuth(options), credential);
-    } else {
+    if (credential.kind !== "oauth") {
       yield* openaiCompatKimi.stream!(messages, options, credential);
+      return;
+    }
+    try {
+      yield* anthropicAdapter.stream!(messages, prepOAuth(options), credential);
+    } catch (err) {
+      throw relabelProviderError(err, KIMI_LABEL);
     }
   },
 };

package/src/ai/providers/openai-compatible.ts

@@ -1,6 +1,8 @@
 import type { ProviderAdapter, CallOptions, ProviderName } from "../types";
 import type { Credential } from "../../auth";
 import { openaiAdapter } from "./openai";
+import { relabelProviderError } from "./errors";
+import { companyLabel } from "../model-catalog";
 
 /**
  * Factory for OpenAI-compatible providers (LM Studio, xAI/Grok, …). They all speak
@@ -14,6 +16,7 @@ const KEYLESS: Credential = { kind: "none", provider: "openai" };
 
 export function makeOpenAICompatibleAdapter(opts: { name: ProviderName; baseUrl: string; keyless?: boolean; thinkingFormat?: CallOptions["reasoningFormat"] }): ProviderAdapter {
   const prefix = `${opts.name}/`;
+  const label = companyLabel(opts.name);
   const prep = (o: CallOptions): CallOptions => ({
     ...o,
     model: o.model.startsWith(prefix) ? o.model.slice(prefix.length) : o.model,
@@ -23,12 +26,26 @@ export function makeOpenAICompatibleAdapter(opts: { name: ProviderName; baseUrl:
     reasoningFormat: o.reasoningFormat ?? opts.thinkingFormat,
   });
   const credFor = (c: Credential): Credential => (opts.keyless ? KEYLESS : c);
+  // `openaiAdapter` hardcodes "OpenAI" as the provider label on every thrown
+  // ProviderHttpError/ProviderStreamError — relabel to the REAL backend (e.g. "Groq",
+  // "DeepSeek") so friendlyProviderError/the fallback classifier/the user all see the
+  // true account that needs attention (auth, billing, rate limit) instead of OpenAI's.
   return {
     name: opts.name,
     supportsNativeTools: openaiAdapter.supportsNativeTools,
-    call: (messages, options, credential) => openaiAdapter.call(messages, prep(options), credFor(credential)),
+    call: async (messages, options, credential) => {
+      try {
+        return await openaiAdapter.call(messages, prep(options), credFor(credential));
+      } catch (err) {
+        throw relabelProviderError(err, label);
+      }
+    },
     async *stream(messages, options, credential) {
-      yield* openaiAdapter.stream!(messages, prep(options), credFor(credential));
+      try {
+        yield* openaiAdapter.stream!(messages, prep(options), credFor(credential));
+      } catch (err) {
+        throw relabelProviderError(err, label);
+      }
     },
   };
 }

package/src/commands/launch/route-slash.ts

@@ -75,17 +75,21 @@ export function runRouteSlash(input: string, ctx: RouteSlashCtx): RouteSlashResu
     if (isRealDecision(ctx.lastRouteDecision)) {
       lines.push(`last decision: ${ctx.lastRouteDecision.tier} → ${ctx.lastRouteDecision.model} (${ctx.lastRouteDecision.source}: ${ctx.lastRouteDecision.signals.join(", ") || "none"}, confidence ${ctx.lastRouteDecision.confidence.toFixed(2)})`);
     }
-    // A model pin (`--model`/`/model`) unconditionally blocks routing regardless of
-    // this session's on/off toggle — surface that explicitly here, since "routing: on"
-    // read alone is misleading if it will never actually evaluate a prompt. Use
-    // /model auto to release the pin and let routing resume.
-    if (ctx.pinnedModel) {
-      lines.push(`note: model pinned to '${ctx.pinnedModel}' this session — routing will not evaluate any prompt until the pin is cleared (/model auto)`);
+    // A model pin (`--model`/`/model`) blocks routing UNLESS the user explicitly ran
+    // `/route on` this session — that explicit toggle wins over a prior pin (see
+    // `routeOverridesPin` in launch.ts's `runTurn`) so routing actually evaluates
+    // every prompt as requested. Surface the distinction here, since "routing: on"
+    // read alone would otherwise be misleading about whether it's actually pinned.
+    if (ctx.pinnedModel && ctx.sessionRouteOverride !== true) {
+      lines.push(`note: model pinned to '${ctx.pinnedModel}' this session — routing will not evaluate any prompt until the pin is cleared (/model auto) or you run '/route on' to override the pin`);
+    } else if (ctx.pinnedModel && ctx.sessionRouteOverride === true) {
+      lines.push(`note: model pinned to '${ctx.pinnedModel}', but '/route on' overrides the pin — routing will evaluate every prompt`);
     }
     return { lines };
   }
 
 
+
   if (sub === "on") {
     return { sessionRouteOverride: true, lines: ["routing: on (this session)"] };
   }

package/src/tui/app.ts

@@ -1438,6 +1438,33 @@ export class LaunchTui {
    *  block shows only the most-recent lines, capped at ~30% of the screen height (a
    *  ceiling guards a tall terminal), so it grows with the stream and shrinks with the
    *  viewport. Returns [] when there is nothing to show. */
+  /** gjc-parity multi-line parallel-subagent panel: when a fan-out `task` batch has
+   *  MORE THAN ONE concurrent slot live, render one status line PER active slot
+   *  (most-recently-touched first) instead of collapsing everything into a single
+   *  "+N more running" summary line (see `currentActivity()`). A single/detached
+   *  subagent still uses the plain status-line path — this panel exists specifically
+   *  to make a truly PARALLEL batch visibly read as parallel: every worker's latest
+   *  activity is on screen at once, capped so a large fan-out can't blow the frame. */
+  private static readonly SUBAGENT_PANEL_MAX_ROWS = 6;
+  private renderSubagentPanel(cols: number): string[] {
+    if (this.subagentLiveSlots.size <= 1) return [];
+    const dim = this.theme.color ? chalk.dim : (s: string) => s;
+    const accent = this.theme.color ? accentPaint(this.theme) : (s: string) => s;
+    const spin = this.theme.color ? accent(this.spinner.current()) : this.spinner.current();
+    const order = [...this.subagentLiveOrder].reverse();
+    const shown = order.slice(0, LaunchTui.SUBAGENT_PANEL_MAX_ROWS);
+    const extra = order.length - shown.length;
+    const wrapW = Math.max(8, cols - 4);
+    const lines = shown.map(slot => {
+      const raw = this.subagentLiveSlots.get(slot) ?? "";
+      return `  ${spin} ${dim(truncateToWidth(raw, wrapW))}`;
+    });
+    const header = dim(`parallel · ${this.subagentLiveSlots.size} running`);
+    const rows = [header, ...lines];
+    if (extra > 0) rows.push(dim(`  … +${extra} more running`));
+    return rows;
+  }
+
   private renderLiveBlock(label: string, text: string, cols: number, rows: number, ceiling: number, cacheKey = label): string[] {
     const dim = this.theme.color ? chalk.dim : (s: string) => s;
     if (!text.trim()) return [];
@@ -1616,6 +1643,14 @@ export class LaunchTui {
     if (this.runningTool && this.liveToolOutput.trim()) {
       tail.push(...this.renderLiveBlock("Output", this.liveToolOutput, cols, rows, 8));
     }
+    // Parallel subagent panel (gjc parity): a fan-out `task` batch with more than one
+    // concurrent slot live gets its OWN multi-line block — one row per active worker —
+    // so a genuinely parallel batch reads as parallel instead of a single rotating line.
+    if (this.subagentActive) {
+      tail.push(...this.renderSubagentPanel(cols));
+    }
+
+
 
     // Live status field: unboxed thinking line + compact metrics row. The model's
     // streamed activity is uniform across providers via streamingActivity and keeps
@@ -1778,9 +1813,16 @@ export class LaunchTui {
       const phase = (this.tickCount * 0.05) % 1;
       const grad = themeGradient(this.theme, idx);
       const palette = [grad.from, grad.to];
-
       if (fit) {
         bottom.push("");
+        // Live status field: unboxed thinking line + compact metrics row. The
+        // streamed activity is uniform across providers, with the ⟦esc⟧ cancel hint
+        // right-aligned and no misleading step counter.
+        if (this.subagentActive) {
+          for (const line of this.renderSubagentPanel(innerWidth)) bottom.push(line);
+        }
+
+
         if (this.turnTitle) {
           const arrow = this.unicode ? "▸" : ">";
           const titleLine = `  ${arrow} ${this.turnTitle}`;

package/src/util/provider-error.ts

@@ -6,6 +6,7 @@
  */
 import { isUsageLimitError, isRefusalError, isConnectionError, ConnectionContextError } from "./retry";
 import { companyLabel } from "../ai/model-catalog";
+import { ProviderHttpError, ProviderStreamError } from "../ai/providers/errors";
 // Re-export: engine.ts and callers import the refusal predicate from here; the
 // definition lives in retry.ts so defaultRetryable can fail fast without a cycle.
 export { isRefusalError } from "./retry";
@@ -15,8 +16,8 @@ export { isRefusalError } from "./retry";
  *  mismatch) — when the PROVIDER says the prompt doesn't fit, the loop can react
  *  (reactive trim + one retry) instead of dying on an opaque 400 (round-6 #4). */
 export function isContextOverflowError(err: unknown): boolean {
-  const msg = (err as Error)?.message ?? String(err);
-  const status = (err as { status?: number })?.status;
+  const msg = err instanceof Error ? err.message : String(err);
+  const status = statusOf(err);
   const pattern = /context[ _-]?length|context window|prompt is too long|input is too long|too many tokens|maximum (input|context)|exceeds.{0,30}(context|token)/i;
   if (pattern.test(msg)) return true;
   return status === 413; // payload-too-large is always an overflow signal
@@ -32,6 +33,43 @@ function formatDuration(ms: number): string {
   return rem ? `~${hours}h ${rem}m` : `~${hours}h`;
 }
 
+/** Narrow an unknown error to one carrying a numeric `.status` field — covers the
+ *  known structured classes AND ad-hoc errors a caller/test attaches `.status` to
+ *  directly (`Object.assign(new Error(...), { status: 413 })`), matching the prior
+ *  permissive cast-based read without an unchecked `as`. */
+function hasNumericStatus(err: unknown): err is { status: number } {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    "status" in err &&
+    typeof err.status === "number"
+  );
+}
+
+/** True provider label for an error, when it's known: `ProviderHttpError`/
+ *  `ProviderStreamError` always carry the ACTUAL backend's DISPLAY label (already
+ *  `companyLabel`'d at every throw site — see `relabelProviderError`'s callers), so
+ *  use it as-is rather than guessing from message text. `undefined` for anything else
+ *  (bare `Error`, a re-wrapped doneReason string, …), letting the caller fall back to
+ *  the regex-based guess below. */
+function knownErrorProvider(err: unknown): string | undefined {
+  if (err instanceof ProviderHttpError || err instanceof ProviderStreamError) {
+    return err.provider;
+  }
+  return undefined;
+}
+
+function statusOf(err: unknown): number | undefined {
+  if (err instanceof ProviderHttpError || err instanceof ProviderStreamError) {
+    return err.status;
+  }
+  return hasNumericStatus(err) ? err.status : undefined;
+}
+
+function retryAfterMsOf(err: unknown): number | undefined {
+  return err instanceof ProviderHttpError ? err.retryAfterMs : undefined;
+}
+
 export function friendlyProviderError(err: unknown): string {
   if (err instanceof ConnectionContextError) {
     const provider = companyLabel(err.provider);
@@ -45,23 +83,32 @@ export function friendlyProviderError(err: unknown): string {
   if (isConnectionError(err)) {
     return `Could not connect to the provider. Check the configured base URL, your network connection, or switch model with /model.`;
   }
-  const msg = (err as Error)?.message ?? String(err);
-  const status = (err as { status?: number })?.status;
-  const provider = /antigravity/i.test(msg)
-    ? "Antigravity"
-    : /anthropic/i.test(msg)
-      ? "Anthropic"
-      : /openai/i.test(msg)
-        ? "OpenAI"
-        : /gemini|google/i.test(msg)
-          ? "Gemini"
-          : "the provider";
+  const msg = err instanceof Error ? err.message : String(err);
+  const status = statusOf(err);
+  // Prefer the error's OWN carried provider (accurate even for compat backends like
+  // Tencent/groq that speak Anthropic's/OpenAI's wire protocol — see
+  // `relabelProviderError`); only guess from message text for errors that never
+  // carried a `.provider` field (bare Error, a re-wrapped doneReason string, …).
+  const provider = knownErrorProvider(err) ?? (
+    /antigravity/i.test(msg)
+      ? "Antigravity"
+      : /anthropic/i.test(msg)
+        ? "Anthropic"
+        : /openai/i.test(msg)
+          ? "OpenAI"
+          : /gemini|google/i.test(msg)
+            ? "Gemini"
+            : "the provider"
+  );
 
   if (isUsageLimitError(err)) {
     return `${provider} usage/quota limit reached — this window will not clear in seconds, so auto-retry was skipped. Switch model with /model (e.g. a local ollama model), use another provider, or wait for the limit window to reset.`;
   }
+  if (status === 402 || /\b402\b/.test(msg) || /payment required|insufficient credit|billing (?:is )?not enabled|free trial quota/i.test(msg)) {
+    return `${provider} requires billing/payment on this account (HTTP 402) — free trial quota exhausted or postpaid billing not enabled. Enable billing on the ${provider} account, or switch model with /model.`;
+  }
   if (status === 429 || /\b429\b/.test(msg) || /rate[ _]?limit/i.test(msg)) {
-    const retryAfterMs = (err as { retryAfterMs?: number })?.retryAfterMs;
+    const retryAfterMs = retryAfterMsOf(err);
     const retry = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs > 0
       ? ` Server requested retry after ${formatDuration(retryAfterMs)}.`
       : "";
@@ -70,7 +117,7 @@ export function friendlyProviderError(err: unknown): string {
   if (status === 401 || status === 403 || /\b40[13]\b/.test(msg)) {
     return `${provider} rejected the credential (HTTP ${status ?? "401/403"}). Run 'jeo auth status', re-login with /provider login <name>, and for Antigravity prefer '/provider login antigravity' (gemini login only works when the Cloud Code Assist backend authorizes that token).`;
   }
-  if ((err as { name?: string })?.name === "TimeoutError" || /the operation timed out/i.test(msg)) {
+  if ((err instanceof Error && err.name === "TimeoutError") || /the operation timed out/i.test(msg)) {
     return `${provider} did not complete the request within the call timeout (default 30min). This is expected for a HIGH/XHIGH-reasoning-effort completion that legitimately runs long on a hard problem — raise JEO_CALL_TIMEOUT_MS (ms) if this recurs, or lower the thinking level with /model.`;
   }
   if (/exceeded the overall deadline \(JEO_STREAM_MAX_MS\)/i.test(msg)) {