jeo-code 0.8.16 → 0.8.18

package/CHANGELOG.md

@@ -6,6 +6,44 @@ 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.18] - 2026-07-09
+_"라우팅 매 프롬프트마다 변경되는지, route why 의도대로 동작하는지 검증하고 배포할게있는지 확인해줘" — 2 parallel subagents live-verified per-prompt routing + `/route why` (including the previously-only-unit-tested post-call equivalent-model fallback path, now reproduced against a real mock 500-error server) and audited a disconnected `RouteHistory` class shipped as incomplete scaffolding in 0.8.16/0.8.17 (class + 11 tests existed, but nothing ever called it — no `/route history` subcommand, no wiring into the turn loop). Live testing also surfaced one real bug: the TUI footer's model/provider label never updated after a mid-turn fallback, staying on the pre-fallback model for the rest of that turn's render even though the backend decision (`lastRouteDecision`) was already correct._
+
+### Fixed
+- **TUI footer no longer shows a stale model after a mid-turn equivalent-pool fallback** (`src/tui/app.ts`, `src/commands/launch.ts`) — the footer's `model`/`provider` fields were set once at `LaunchTui` construction and never updated when `launch.ts`'s post-call fallback loop (routed model hit a persistent server-side error, rate limit, etc.) switched `activeModel` mid-turn; the status bar kept showing the ORIGINAL pre-fallback model for the remainder of that turn even though the reply actually came from the fallback model. Added an `onModelSwitch(model, provider)` event, fired from the fallback loop right alongside the existing `[route] … switching to equivalent …` notice, that updates the live footer in place.
+
+### Added
+- **`/route history [n]`** (`src/agent/route-history.ts`, `src/commands/launch/route-slash.ts`, registered in `src/tui/components/slash.ts`) — wires the `RouteHistory` class (shipped disconnected in the prior commit) into the live turn loop: a session-scoped bounded FIFO (never persisted) records every real routing decision — both the pre-call routed pick and any mid-turn equivalent-model fallback that actually served the turn — so history reflects reality, not a since-superseded pre-call guess. `/route history [n]` prints the last n (default 10, non-positive/non-numeric args fall back to the default) as `turn N: tier -> model (source, confidence X.XX)`.
+
+### Removed
+- **`IMPROVEMENT_SUMMARY.md`, `REVIEW.md`** — stray AI-session working notes from the prior commit, never referenced by `README.md`, `CHANGELOG.md`, or `package.json`'s `files` allowlist.
+
+### Verified
+- Live PTY re-verification (`bun src/cli.ts`, isolated `JEO_CONFIG_DIR`, real Anthropic credentials): 5 prompts of varying complexity in one session routed to 5 distinct tier/model pairs (trivial→claude-haiku-4-5, complex→claude-fable-5, trivial→claude-haiku-4-5, high→claude-sonnet-5, trivial→claude-haiku-4-5); `/route why` and `/route status` matched the actual serving model on every turn.
+- Live post-call-fallback reproduction: a real `Bun.serve` mock returning HTTP 500 on every call forced `launch.ts`'s equivalent-pool fallback to fire mid-turn; `/route why` immediately after correctly reported the POST-fallback model and a `warning: … switched to equivalent …` field, not the original pre-call pick.
+- `bun test test/route-history.test.ts test/route-slash.test.ts test/launch-prompt-routing.test.ts` — 69 pass / 0 fail.
+- `bun test test/tui-app.test.ts` — 51 pass / 0 fail (50 pre-existing + 1 new, covering the footer live-update fix).
+- Full `bun test` — 2885 pass / 0 fail across 290 files.
+- `bun run typecheck` — no errors.
+
+## [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

@@ -79,7 +79,7 @@ jeo --tmux               # 独立した tmux セッションで実行
 | `/provider login <name>` · `/logout` | 入力欄から OAuth ログイン/ログアウト |
 | `/agents [role]` · `/subagent` | ロール別(executor/planner/architect/critic)モデル・thinking・ステップ設定 |
 | `/thinking [level]` | デフォルト推論予算(low…xhigh)の表示/設定 |
-| `/route [status\|on\|off\|why]` | セッション単位のプロンプトベース・モデルルーティングの切替 · 直近のルーティング判断の説明(設定済み資格情報 — OAuth または API キー — が実際に提供するモデルの中でのみ自動ルーティング) |
+| `/route [status\|on\|off\|why\|history [n]]` | セッション単位のプロンプトベース・モデルルーティングの切替 · 直近のルーティング判断の説明 · `history [n]` はこのセッションの直近 n 件(デフォルト 10 件)のルーティング判断を表示(設定済み資格情報 — OAuth または API キー — が実際に提供するモデルの中でのみ自動ルーティング) |
 | `/fast [on\|off\|status]` | 現在のモデルが low 推論をサポートする場合に fast thinking モードを切替 |
 | `/skill` · `$<skill> [intent]` | ワークフロースキルの一覧/実行(`$team "task"` 形式) |
 | `/view` · `/diff` · `/find` · `/search` | コード表示、git diff、ファイル/パターン検索 |
@@ -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.18]** (2026-07-09) — "라우팅 매 프롬프트마다 변경되는지, route why 의도대로 동작하는지 검증하고 배포할게있는지 확인해줘" — 2 parallel subagents live-verified per-prompt routing + `/route why` (including the previously-only-unit-tested post-call equivalent-model fallback path, now reproduced against a real mock 500-error server) and audited a disconnected `RouteHistory` class shipped as incomplete scaffolding in 0.8.16/0.8.17 (class + 11 tests existed, but nothing ever called it — no `/route history` subcommand, no wiring into the turn loop). Live testing also surfaced one real bug: the TUI footer's model/provider label never updated after a mid-turn fallback, staying on the pre-fallback model for the rest of that turn's render even though the backend decision (`lastRouteDecision`) was already correct.
+- **[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

@@ -80,7 +80,7 @@ jeo --tmux               # 독립 tmux 세션에서 실행
 | `/provider login <name>` · `/logout` | 입력창에서 OAuth 로그인/로그아웃 |
 | `/agents [role]` · `/subagent` | 역할별(executor/planner/architect/critic) 모델·thinking·스텝 구성 |
 | `/thinking [level]` | 기본 추론 예산(low…xhigh) 조회/설정 |
-| `/route [status\|on\|off\|why]` | 세션별 프롬프트 기반 모델 라우팅 켜기/끄기 · 마지막 라우팅 결정 설명(설정된 자격증명 — OAuth 또는 API 키 — 이 실제로 서비스하는 모델 안에서만 자동 라우팅) |
+| `/route [status\|on\|off\|why\|history [n]]` | 세션별 프롬프트 기반 모델 라우팅 켜기/끄기 · 마지막 라우팅 결정 설명 · `history [n]`은 이번 세션의 최근 n개(기본 10개) 라우팅 결정 표시(설정된 자격증명 — OAuth 또는 API 키 — 이 실제로 서비스하는 모델 안에서만 자동 라우팅) |
 | `/fast [on\|off\|status]` | 현재 모델이 low 추론을 지원하면 fast thinking 모드를 켜고 끔 |
 | `/skill` · `$<skill> [intent]` | 워크플로 스킬 목록/실행(`$team "작업"` 스타일) |
 | `/view` · `/diff` · `/find` · `/search` | 코드 보기, git diff, 파일/패턴 검색 |
@@ -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.18]** (2026-07-09) — "라우팅 매 프롬프트마다 변경되는지, route why 의도대로 동작하는지 검증하고 배포할게있는지 확인해줘" — 2 parallel subagents live-verified per-prompt routing + `/route why` (including the previously-only-unit-tested post-call equivalent-model fallback path, now reproduced against a real mock 500-error server) and audited a disconnected `RouteHistory` class shipped as incomplete scaffolding in 0.8.16/0.8.17 (class + 11 tests existed, but nothing ever called it — no `/route history` subcommand, no wiring into the turn loop). Live testing also surfaced one real bug: the TUI footer's model/provider label never updated after a mid-turn fallback, staying on the pre-fallback model for the rest of that turn's render even though the backend decision (`lastRouteDecision`) was already correct.
+- **[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

@@ -40,7 +40,7 @@ Run `jeo` inside a repository and it reads files, edits them, runs commands, and
 
 ## Highlights
 
-- **Prompt routing (cost-aware, credential-aware)** — every turn can auto-route to a tier-appropriate model among only the providers your configured credentials actually serve (`/route [status|on|off|why]`), with a live equivalent-model fallback whenever a routed provider is rate-limited, unauthenticated, unreachable, or silently times out — see `/route why` for the last decision.
+- **Prompt routing (cost-aware, credential-aware)** — every turn can auto-route to a tier-appropriate model among only the providers your configured credentials actually serve (`/route [status|on|off|why|history]`), with a live equivalent-model fallback whenever a routed provider is rate-limited, unauthenticated, unreachable, or silently times out — see `/route why` for the last decision, `/route history` for the recent ones.
 - **Computer use (desktop automation)** — a fail-closed `computer` tool (screenshot/click/type/scroll/drag/batch) gated by both a config flag and an independent kill-switch/heartbeat supervisor; toggle it for the current session with `/computer [status|on|off]` without touching `~/.jeo/config.json`.
 - **Multi-provider, one loop** — Anthropic / OpenAI (+Codex) / Gemini / Antigravity / Ollama / LM Studio, plus 20+ OpenAI- and Anthropic-compatible clouds (Groq, DeepSeek, Mistral, OpenRouter, xAI, Kimi, z.ai, …), all behind one uniform JSON tool loop. OAuth login happens from the input box (`/provider login`), every model pick persists as the new default, and prompt routing only auto-selects usable credentialed paths: Gemini OAuth goes through the provider-qualified `antigravity/*` agent set (Gemini 3.5 Flash tiers, Gemini 3.1 Pro, Claude Sonnet/Opus 4.6), never public `google/gemini-*` rows that require `GEMINI_API_KEY`; if a configured route points at an unready provider, jeo switches to an equivalent credentialed tier model before falling back to the default.
 
@@ -85,7 +85,7 @@ Inside the `jeo` REPL (Tab autocompletes; `/` opens the palette).
 | `/provider login <name>` · `/logout` | OAuth login/logout from the input box |
 | `/agents [role]` · `/subagent` | Per-role (executor/planner/architect/critic) model · thinking · step config |
 | `/thinking [level]` | Show/set default reasoning budget (low…xhigh) |
-| `/route [status\|on\|off\|why]` | Toggle prompt-based model routing for this session · explain the last routing decision (auto-routes each turn to a tier-appropriate model among the models your configured credentials — OAuth or API key — actually serve, and switches to an equivalent tier model when a configured route is unready) |
+| `/route [status\|on\|off\|why\|history [n]]` | Toggle prompt-based model routing for this session · explain the last routing decision · `history [n]` lists the last n (default 10) routing decisions this session (auto-routes each turn to a tier-appropriate model among the models your configured credentials — OAuth or API key — actually serve, and switches to an equivalent tier model when a configured route is unready) |
 | `/fast [on\|off\|status]` | Toggle fast thinking mode when the active model advertises low reasoning |
 | `/skill` · `$<skill> [intent]` | List/run workflow skills (`$team "task"` style) |
 | `/view` · `/diff` · `/find` · `/search` | Code view, git diff, file/pattern search |
@@ -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.18]** (2026-07-09) — "라우팅 매 프롬프트마다 변경되는지, route why 의도대로 동작하는지 검증하고 배포할게있는지 확인해줘" — 2 parallel subagents live-verified per-prompt routing + `/route why` (including the previously-only-unit-tested post-call equivalent-model fallback path, now reproduced against a real mock 500-error server) and audited a disconnected `RouteHistory` class shipped as incomplete scaffolding in 0.8.16/0.8.17 (class + 11 tests existed, but nothing ever called it — no `/route history` subcommand, no wiring into the turn loop). Live testing also surfaced one real bug: the TUI footer's model/provider label never updated after a mid-turn fallback, staying on the pre-fallback model for the rest of that turn's render even though the backend decision (`lastRouteDecision`) was already correct.
+- **[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

@@ -79,7 +79,7 @@ jeo --tmux               # 在独立 tmux 会话中运行
 | `/provider login <name>` · `/logout` | 在输入框内 OAuth 登录/登出 |
 | `/agents [role]` · `/subagent` | 按角色(executor/planner/architect/critic)配置模型·thinking·步数 |
 | `/thinking [level]` | 查看/设置默认推理预算(low…xhigh) |
-| `/route [status\|on\|off\|why]` | 切换本会话的基于提示词的模型路由 · 解释最近一次路由决策(仅在已配置凭证 — OAuth 或 API 密钥 — 实际可用的模型内自动路由) |
+| `/route [status\|on\|off\|why\|history [n]]` | 切换本会话的基于提示词的模型路由 · 解释最近一次路由决策 · `history [n]` 列出本会话最近 n 条(默认 10 条)路由决策(仅在已配置凭证 — OAuth 或 API 密钥 — 实际可用的模型内自动路由) |
 | `/fast [on\|off\|status]` | 当前模型支持 low 推理时切换 fast thinking 模式 |
 | `/skill` · `$<skill> [intent]` | 列出/运行工作流技能(`$team "任务"` 风格) |
 | `/view` · `/diff` · `/find` · `/search` | 代码查看、git diff、文件/模式搜索 |
@@ -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.18]** (2026-07-09) — "라우팅 매 프롬프트마다 변경되는지, route why 의도대로 동작하는지 검증하고 배포할게있는지 확인해줘" — 2 parallel subagents live-verified per-prompt routing + `/route why` (including the previously-only-unit-tested post-call equivalent-model fallback path, now reproduced against a real mock 500-error server) and audited a disconnected `RouteHistory` class shipped as incomplete scaffolding in 0.8.16/0.8.17 (class + 11 tests existed, but nothing ever called it — no `/route history` subcommand, no wiring into the turn loop). Live testing also surfaced one real bug: the TUI footer's model/provider label never updated after a mid-turn fallback, staying on the pre-fallback model for the rest of that turn's render even though the backend decision (`lastRouteDecision`) was already correct.
+- **[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.18",
   "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

@@ -1,14 +1,15 @@
 /**
  * `/route` slash-command handler extracted from launch.ts.
  *
- * Handles `/route [status|on|off|why]` (default/`status`: report the effective
- * session routing state + the last decision, if any; `on`/`off`: toggle a
- * SESSION-LOCAL override of `config.routing.enabled`; `why`: explain the last
- * routing decision in detail). This block shares mutable REPL state
- * (`sessionRouteOverride`, `lastRouteDecision`) with `runTurn`'s own routing
- * insertion, so the caller passes the current values in via an explicit
- * context object and reads back a result object instead of this function
- * closing over REPL state directly.
+ * Handles `/route [status|on|off|why|history]` (default/`status`: report the
+ * effective session routing state + the last decision, if any; `on`/`off`:
+ * toggle a SESSION-LOCAL override of `config.routing.enabled`; `why`: explain
+ * the last routing decision in detail; `history [n]`: print the last `n`
+ * (default 10) recorded decisions, one per line). This block shares mutable
+ * REPL state (`sessionRouteOverride`, `lastRouteDecision`, `routeHistory`)
+ * with `runTurn`'s own routing insertion, so the caller passes the current
+ * values in via an explicit context object and reads back a result object
+ * instead of this function closing over REPL state directly.
  *
  * Session-level toggle only — `sessionRouteOverride` is never persisted to
  * `~/.jeo/config.json` (mirrors `/thinking` being session-only vs. `/model
@@ -17,6 +18,7 @@
  */
 
 import type { RouteDecision } from "../../agent/prompt-router";
+import type { RouteHistoryEntry } from "../../agent/route-history";
 
 export interface RouteSlashCtx {
   sessionRouteOverride: boolean | undefined;
@@ -28,9 +30,13 @@ export interface RouteSlashCtx {
    *  never changes routing's actual gating logic (`!sessionModel` in launch.ts's
    *  `runTurn` stays the single source of truth for whether routing engages). */
   pinnedModel?: string;
+  /** Chronological (oldest-first) snapshot of this session's `RouteHistory`
+   *  (`routeHistory.getAll()`), read fresh by the caller for `/route history`. */
+  routeHistory: RouteHistoryEntry[];
 }
 
 
+
 export interface RouteSlashResult {
   /** Present only when changed by "on"/"off". */
   sessionRouteOverride?: boolean | undefined;
@@ -38,7 +44,7 @@ export interface RouteSlashResult {
   lines: string[];
 }
 
-const USAGE = "Usage: /route [status|on|off|why]";
+const USAGE = "Usage: /route [status|on|off|why|history [n]]";
 
 function isRealDecision(decision: RouteDecision | { note: string } | null): decision is RouteDecision {
   return !!decision && "model" in decision;
@@ -61,13 +67,25 @@ function explainDecision(decision: RouteDecision | { note: string } | null): str
 }
 
 /**
- * Handle `/route [status|on|off|why]`. Extracted for the same reason as
- * `/model`: shares REPL-local routing state with `runTurn` via an explicit
- * ctx/result object rather than closing over it.
+ * Format the last `n` history entries (default 10) as one line each:
+ * `turn N: tier -> model (source, confidence X.XX)`, oldest of the selected
+ * window first — matches `getAll()`'s chronological ordering.
+ */
+function formatHistory(entries: RouteHistoryEntry[], n: number): string[] {
+  if (entries.length === 0) return ["No routing decisions recorded yet this session."];
+  const selected = n > 0 ? entries.slice(Math.max(0, entries.length - n)) : [];
+  if (selected.length === 0) return ["No routing decisions recorded yet this session."];
+  return selected.map((e) => `turn ${e.turnNumber}: ${e.tier} -> ${e.model} (${e.source}, confidence ${e.confidence.toFixed(2)})`);
+}
+
+/**
+ * Handle `/route [status|on|off|why|history]`. Extracted for the same reason
+ * as `/model`: shares REPL-local routing state with `runTurn` via an
+ * explicit ctx/result object rather than closing over it.
  */
 export function runRouteSlash(input: string, ctx: RouteSlashCtx): RouteSlashResult {
   const rest = input.slice("/route".length).trim();
-  const [sub] = rest.split(/\s+/).filter(Boolean);
+  const [sub, arg] = rest.split(/\s+/).filter(Boolean);
   const effective = ctx.sessionRouteOverride ?? ctx.routingConfigEnabled;
 
   if (!sub || sub === "status") {
@@ -75,17 +93,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)"] };
   }
@@ -98,5 +120,15 @@ export function runRouteSlash(input: string, ctx: RouteSlashCtx): RouteSlashResu
     return { lines: explainDecision(ctx.lastRouteDecision) };
   }
 
+  if (sub === "history") {
+    // Only a finite POSITIVE count selects a window; 0, negatives, and
+    // non-numeric args (`bogus`) all fall back to the default 10 rather than
+    // silently printing the empty-history message when decisions actually
+    // exist (that message must mean "nothing recorded", never "you asked for 0").
+    const parsed = arg !== undefined ? Number.parseInt(arg, 10) : 10;
+    const n = Number.isFinite(parsed) && parsed > 0 ? parsed : 10;
+    return { lines: formatHistory(ctx.routeHistory, n) };
+  }
+
   return { lines: [`Unknown /route subcommand: ${sub}`, USAGE] };
 }

package/src/commands/launch.ts

@@ -52,6 +52,7 @@ import { describeModel, describeAllProviders, describeProvider, resolveProvider,
 import type { ProviderModelsResult, PickEntry, ProviderName, ModelRole, ThinkLevel } from "../ai";
 import { readGoalState, writeGoalState, clearGoalState, verifyGoal } from "../agent/goal-verifier";
 import { routePrompt, deriveCacheSessionKey, warnOnce, tierModelPool, selectFromPool, PROMPT_TIERS, withRoutingTierSetting, inferTierForModel, type PromptTier, type RouteDecision } from "../agent/prompt-router";
+import { RouteHistory } from "../agent/route-history";
 
 import { isRateLimitError, isUsageLimitError, isConnectionError } from "../util/retry";
 
@@ -659,6 +660,10 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   let sessionRouteOverride: boolean | undefined;
   // Last routing decision (or the reason none applied) — /route why reads this.
   let lastRouteDecision: RouteDecision | { note: string } | null = null;
+  // Bounded FIFO of this session's routing decisions — /route history reads this.
+  // Same lifecycle scope as `lastRouteDecision`: one instance per REPL session,
+  // never persisted to config.
+  const routeHistory = new RouteHistory();
   // Computer-use session override: undefined = follow config.computer.enabled, true/false = /computer on|off wins this session.
   let sessionComputerOverride: boolean | undefined;
 
@@ -1025,6 +1030,10 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       }
     }
     lastRouteDecision = routed ?? (routeVetoNote ? { note: routeVetoNote } : routingEnabled && (routeOverridesPin || !sessionModel) ? { note: "routing produced no decision (fail-open)" } : { note: "routing not active this turn" });
+    // Only a REAL decision (not a `{note}` placeholder) is worth recording —
+    // `/route history` exists to show what actually routed, not every turn's
+    // gating outcome.
+    if (routed) routeHistory.add(routed);
     // Explicit /model always wins UNLESS an explicit `/route on` this session opted
     // back into per-prompt routing (`routeOverridesPin`); otherwise `routed` is only
     // ever computed when `!sessionModel`.
@@ -1465,9 +1474,19 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           contextTokens = catalogMetadata(activeModel)?.contextTokens;
           fallbackBaseDecision = { ...fallbackBaseDecision, model: activeModel };
           lastRouteDecision = { ...fallbackBaseDecision, warning: `model '${previousModel}' ${routedFailureReason}; switched to equivalent '${activeModel}'` };
+          // Post-call fallback: the pre-call `routed` pick (already recorded above,
+          // if any) got superseded mid-turn — record the decision that ACTUALLY
+          // served the turn so `/route history`/`why` reflect reality, not a
+          // since-abandoned pre-call guess.
+          routeHistory.add(lastRouteDecision);
           const notice = `[route] model '${previousModel}' ${routedFailureReason}; switching to equivalent '${activeModel}' for this turn.`;
-          if (tui) tui.events().onNotice?.(notice);
-          else console.log(notice);
+          if (tui) {
+            const { provider: fallbackProvider } = await describeModel(activeModel, turnConfig);
+            tui.events().onModelSwitch?.(activeModel, fallbackProvider);
+            tui.events().onNotice?.(notice);
+          } else {
+            console.log(notice);
+          }
           result = await runLoopWithModel(activeModel, activeThinking, turnSessionKey);
         }
 
@@ -4435,6 +4454,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           routingConfigEnabled: !!cfgNow.routing?.enabled,
           lastRouteDecision,
           pinnedModel: sessionModel,
+          routeHistory: routeHistory.getAll(),
         });
         if (routeResult.sessionRouteOverride !== undefined) sessionRouteOverride = routeResult.sessionRouteOverride;
         for (const line of routeResult.lines) console.log(line);

package/src/tui/app.ts

@@ -92,6 +92,13 @@ export interface AgentEventsLike {
    *  item). The TUI ignores these; launch.ts uses them to persist the final reply's artifacts. */
   onReasoningArtifactStream?(artifact: import("../ai/types").ReasoningArtifact): void;
   onBudget?(limit: number, reason: string): void;
+  /** Fired when the active model changes mid-turn (post-call equivalent-pool fallback,
+   *  launch.ts's `routeFallbackAttempt` loop) — updates the footer's model/provider
+   *  label so the status bar reflects the model that actually serves the REST of the
+   *  turn, instead of staying stuck on the pre-fallback model for the remainder of the
+   *  render (the backend `lastRouteDecision`/`routeHistory` were already correct; only
+   *  this footer label lagged). */
+  onModelSwitch?(model: string, provider?: string): void;
 
 }
 
@@ -696,6 +703,17 @@ export class LaunchTui {
         this.appendLedger(dim(`${mark} ${reason}`) + "\n", "notice");
         this.draw();
       },
+      onModelSwitch: (model: string, provider?: string) => {
+        // Mid-turn equivalent-pool fallback: the footer's model/provider label was
+        // frozen at construction time otherwise, so a post-call reroute (the model
+        // that ACTUALLY produces the rest of the reply) never showed in the status
+        // bar for the remainder of the turn — even though lastRouteDecision/
+        // routeHistory were already correct. Mutate the SAME footer object the
+        // render loop reads every frame; no separate re-render path needed.
+        this.footer.model = model;
+        this.footer.provider = provider;
+        this.draw();
+      },
       onUsage: (u: { inputTokens: number; outputTokens: number }) => {
         // Live cumulative token usage for the turn — shown in the final summary
         // (and available to the footer meter).
@@ -1438,6 +1456,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 +1661,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 +1831,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/tui/components/slash.ts

@@ -43,7 +43,7 @@ export const SLASH_COMMAND_DETAILS: readonly SlashCommandInfo[] = [
   { command: "/logout", usage: "/logout <anthropic|openai|gemini|antigravity>", description: "Remove the stored OAuth token for a provider", group: "models" },
   { command: "/roles", usage: "/roles [tier model]", description: "Show or set model role tiers (smol/slow/plan)", group: "models" },
   { command: "/thinking", usage: "/thinking [level]", description: "Show or set thinking budget (low/medium/high/xhigh)", group: "models" },
-  { command: "/route", usage: "/route [on|off|why]", description: "Show/toggle prompt-based model routing for this session, or explain the last routing decision", group: "models" },
+  { command: "/route", usage: "/route [on|off|why|history [n]]", description: "Show/toggle prompt-based model routing for this session, explain the last routing decision, or list recent routing history", group: "models" },
   { command: "/agents", usage: "/agents [edit|role] [model|#N|thinking L|maxSteps N|reset]", description: "List subagent roles; use /agents edit for the interactive picker or pin role model/settings", group: "subagents" },
   { command: "/subagent", usage: "/subagent [role]", description: "Show the current subagent composition (per-role model · thinking · steps); alias of /agents", group: "subagents" },
   { command: "/view", usage: "/view <file> [a-b]", description: "Render a file with line numbers + light highlight", group: "code" },

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)) {